feat(learn): add article for publishing a typescript package #7279
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
JakobJingleheimer
force-pushed
the
art/publishing-typescript
branch
from
31678d2 to
2d5d359
Compare
|
Jacob you should:
|
This comment was marked as outdated.
This comment was marked as outdated.
Co-authored-by: Augustin Mauroy <[email protected]> Signed-off-by: Jacob Smith <[email protected]>
Thank you! TIL several things 😁
Oh! Yes! |
| "name": "example-ts-pkg", | ||
| "scripts": { | ||
| "test": "node --test './src/**/*.test.ts'", | ||
| "types:check": "tsc --noEmit" |
There was a problem hiding this comment.
I noted this in the other thread, but I would be cautious about this as a default; I really only see people setting noEmit when they're doing a quick check, or are using a bundler or something.
There was a problem hiding this comment.
This is the type "test" command. Why would you want to emit a compilation?
Maybe the names could be better? When I have unit and end-to-end tests with different setups, I split those into different commands like:
test:unittest:e2e
So in that scenario, it could make sense to name types:check → test:types.
But in the sample, there's no differentiation between units and e2e, so then what do I call what is currently test?
There was a problem hiding this comment.
I mean, I guess it's fine, I am just wary of cases where tsc and tsc --noEmit output different errors because the former is doing more. Maybe you'd hit it on prepack and that's okay, but it's a little unfortunate to only hit an error when you go to release...
There was a problem hiding this comment.
Is that likely? I've been doing this for years and never encountered that—am I just very lucky?
There was a problem hiding this comment.
I'm not sure how to gauge "likely", probably unlikely, but they're cases like "tsc failed to write the files", along with potentially some declaration transform errors. (The latter shouldn't actually end up mattering by my reading of the code, though.)
There was a problem hiding this comment.
The specific issues that come up that I can think of are when a declaration file can't reliably be generated because doing so might require referencing entities that are private or non-exported. Trying to figure out why this error is happening can be pretty frustrating, especially if you've been relying a specific pattern over time. Having a divergence between publish/CI probably just makes this even more confusing since most people outside of the person who set up the build won't be aware of any differences.
There was a problem hiding this comment.
tsc failed to write the files
That does sound like an issue that you legitimately wouldn't catch with a dry-run, but also seems a very unlikely issue (and one that could still occur at publishing even if you were using non-dry-run for the test step). It seems an edge-case worth noting but not worth taking a hit every time to avoid something that likely will never happen (if it does, there are a very limited number of causes—two? permissions and storage availability).
The specific issues that come up that I can think of are when a declaration file can't reliably be generated because doing so might require referencing entities that are private or non-exported.
That sounds very detectable for --noEmit; if it doesn't do that, that sounds like a defect in tsc? Why would you need to writing to disk in order to discover it?
But maybe let's take a step back for a second: The reason I wrote the setup this way is because of performance—but perhaps my information is outdated. Last I heard, tsc --noEmit was significantly faster than with emit.
There was a problem hiding this comment.
That sounds very detectable for
--noEmit; if it doesn't do that, that sounds like a defect intsc? Why would you need to writing to disk in order to discover it?
I think as of recent releases (since --isolatedDeclarations), we've actually always checked declaration errors without emit, so I think the only errors one can see differently are just the errors that happen while writing, which may not really be important except in the case where you've somehow accidentally marked output paths as readonly in the FS or something.
But maybe let's take a step back for a second: The reason I wrote the setup this way is because of performance—but perhaps my information is outdated. Last I heard,
tsc --noEmitwas significantly faster than with emit.
It can be, though I think at the scale of this demo, it's definitely not a big difference.
There was a problem hiding this comment.
Is the take-away then that what I have is fine? There is a potentially (and probably likely) significant perf savings, and there're basically no type-related errors this won't catch?
|
|
||
| # Publishing a TypeScript project | ||
|
|
||
| This article augments TypeScript's own [Publishing guide](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) with specifics for native node support. |
There was a problem hiding this comment.
I am sort of questioning linking to this page; reading it, it's pretty out of date and is part of the declaration file section, so sort of misses out on other important stuff.
There was a problem hiding this comment.
Happy to change it to a different one—is there one you had in mind?
|
|
||
| - name: Publish with provenance | ||
| env: | ||
| NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} |
There was a problem hiding this comment.
Is NPM_TOKEN automatically provided somehow? I think we should mention how to get this or avoid automated publishing accordingly. having a separate guide on automated publishing is worthwhile.
There was a problem hiding this comment.
t's not provide automatically. But this GA example from https://docs.npmjs.com/generating-provenance-statements#example-github-actions-workflow
There was a problem hiding this comment.
Would we have enough content for a dedicated guide on automated publishing?
For now, I think let's add a note explaining what the token is and where it comes from: 0f7f993
There was a problem hiding this comment.
There are a ton of problems with automated publishing (discussed above) and I think a separate guide that can fully explain the pros and cons is definitely warranted.
There was a problem hiding this comment.
In that case, sure, happy to do subsequently (subsequently because otherwise we end up with a web of ½ finished, inter-dependent guides, and this doesn't seem like a show-stopper—unless someone strongly thinks that it needs to happen first).
There was a problem hiding this comment.
I've made the case above that it would be better to give no publishing guidance prior to such a properly nuanced guide, then to provide instructions absent nuance - iow, I suggest removing this section entirely and hand-wave over publishing for the time being.
I don't think we can avoid interdependent guides; the reality is too complex to allow for a single "does everything" document imo.
There was a problem hiding this comment.
why not just redirect to npm docs ?
There was a problem hiding this comment.
Oh for sure they'll be inter-dependent. I just want to avoid a bunch of unfinished inter-dependent guides that are stuck in a spiderman meme.
There was a problem hiding this comment.
So let's remove provenance and add note or let the security team write another article about it
Description
Document the recommended way to publish a typescript package
Validation
Related Issues
nodejs/typescript#19
Depends on #7229
Check List
npm run formatto ensure the code follows the style guide.npm run testto check if all tests are passing.npx turbo buildto check if the website builds without errors.