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]>
|
It's not a clean mapping; unfortunately TS doesn't have a |
Looks like there is something: https://www.typescriptlang.org/tsconfig/#target → https://www.npmjs.com/package/@tsconfig/node18 |
|
That's great, thanks! |
github-actions
bot
removed
the
github_actions:pull-request
|
Lighthouse Results
|
Unit Test Coverage Report
Unit Test Report
|
JakobJingleheimer
added
the
github_actions:pull-request
github-actions
bot
removed
the
github_actions:pull-request
JakobJingleheimer
added
the
github_actions:pull-request
github-actions
bot
removed
the
github_actions:pull-request
|
merging per a conversation with @JakobJingleheimer |
|
Thanks all! Happy to iterate if needed 🙂 |
|
|
||
| - Use [dependabot](https://docs.github.com/en/code-security/dependabot) to keep your dependencies current, including those in github actions. It's a very easy set-and-forget configuration. | ||
|
|
||
| - `.nvmrc` comes from [NVM](https://github.com/nvm-sh/nvm), a multi-version manager for node. It allows you to specify the version of node the project should generally use. |
There was a problem hiding this comment.
| - `.nvmrc` comes from [NVM](https://github.com/nvm-sh/nvm), a multi-version manager for node. It allows you to specify the version of node the project should generally use. | |
| - `.nvmrc` comes from [`nvm`](https://github.com/nvm-sh/nvm), a multi-version manager for node. It allows you to specify the version of node the project should generally use. |
|
|
||
| TypeScript has warned that the above code will not behave as intended, just like a unit test warns that code does not behave as intended. They are complementary and verify different things—you should have both. | ||
|
|
||
| Your editor (ex VS Code) likely has built-in support for TypeScript, displaying errors as you work. If not, and/or you missed those, CI will have your back. |
There was a problem hiding this comment.
| Your editor (ex VS Code) likely has built-in support for TypeScript, displaying errors as you work. If not, and/or you missed those, CI will have your back. | |
| Your editor (eg VS Code) likely has built-in support for TypeScript, displaying errors as you work. If not, and/or you missed those, CI will have your back. |
There was a problem hiding this comment.
These are the same 😜 One is english, the other is latin:
ex → example
eg → exempli gratia
There was a problem hiding this comment.
right, but "ex" reads to me as "formerly", "eg" doesn't have the same confusion
There was a problem hiding this comment.
Ah, okay that's better then 🙂
|
|
||
| # This is mostly boilerplate. | ||
|
|
||
| name: Publish to NPM |
There was a problem hiding this comment.
| name: Publish to NPM | |
| name: Publish to npm |
(npm should always be lowercased)
|
|
||
| #### Breaking this down | ||
|
|
||
| Generating type declarations is deterministic: you'll get the same output from the same input, every time. So there is no need to commit these to git. |
There was a problem hiding this comment.
i'm pretty sure this isn't actually true, but either way generated output should never be committed to source control.
There was a problem hiding this comment.
🤔 Oh? I can't think of how it isn't—could you enlighten me?
There was a problem hiding this comment.
I'm sure it's semantically deterministic, but I would be very surprised if the output bytes were actually deterministic (mangled variable names, etc) - and either way, nondeterminism isn't why they shouldn't be committed, "they're generated" is.
There was a problem hiding this comment.
This is type def generation, no transpiling the typescript (which is definitely not deterministic, as indeed variable name mangling etc). Type names are not changed when the def files are generated (that would break the hell out of the type defs).
nondeterminism isn't why they shouldn't be committed, "they're generated" is.
True, but if it's nondeterministic, I shouldn't say it is deterministic.
There was a problem hiding this comment.
ahhh that's fair. you might be right that the type defs are deterministic! but i'd still say that's not important to mention because it's not why they shouldn't be committed.
|
|
||
| [`npm publish`](https://docs.npmjs.com/cli/commands/npm-publish) grabs everything applicable and available at the moment the command is run; so generating type declarations immediately before means those are available and will get picked up. | ||
|
|
||
| By default, `npm publish` grabs (almost) everything (see [Files included in package](https://docs.npmjs.com/cli/commands/npm-publish#files-included-in-package)). In order to keep your published package minimal (see the "Heaviest Objects in the Universe" meme about `node_modules`), you want to exclude certain files (like tests and test fixtures) from from packaging. Add these to the opt-out list specified in [`.npmignore`](https://docs.npmjs.com/cli/using-npm/developers#keeping-files-out-of-your-package); ensure the `!*.d.ts` exception is listed, or the generated type declartions will not be published! Alternatively, you can use [package.json "files"](https://docs.npmjs.com/cli/configuring-npm/package-json#files) to create an opt-in list. |
There was a problem hiding this comment.
| By default, `npm publish` grabs (almost) everything (see [Files included in package](https://docs.npmjs.com/cli/commands/npm-publish#files-included-in-package)). In order to keep your published package minimal (see the "Heaviest Objects in the Universe" meme about `node_modules`), you want to exclude certain files (like tests and test fixtures) from from packaging. Add these to the opt-out list specified in [`.npmignore`](https://docs.npmjs.com/cli/using-npm/developers#keeping-files-out-of-your-package); ensure the `!*.d.ts` exception is listed, or the generated type declartions will not be published! Alternatively, you can use [package.json "files"](https://docs.npmjs.com/cli/configuring-npm/package-json#files) to create an opt-in list. | |
| By default, `npm publish` grabs (almost) everything (see [Files included in package](https://docs.npmjs.com/cli/commands/npm-publish#files-included-in-package)). In order to keep your published package minimal (see the "Heaviest Objects in the Universe" meme about `node_modules`), you want to exclude certain files (like tests and test fixtures) from from packaging. Add these to the opt-out list specified in [`.npmignore`](https://docs.npmjs.com/cli/using-npm/developers#keeping-files-out-of-your-package); ensure the `!*.d.ts` exception is listed, or the generated type declartions will not be published! Alternatively, you can use [package.json "files"](https://docs.npmjs.com/cli/configuring-npm/package-json#files) to create an opt-in list - but if a mistake is made and a file accidentally omitted, your package may be broken for downstream users, so this is a less safe option. |
|
Thanks! I'll open a follow-up soon (on quasi-holiday til this weekend, so not sure if/when I'll have time before then). |
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.