-
Notifications
You must be signed in to change notification settings - Fork 2.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(core): add typescript packaging recipes (#19262)
- Loading branch information
1 parent
892fd4b
commit 51d2fac
Showing
6 changed files
with
244 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
75 changes: 75 additions & 0 deletions
75
docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| ## Compile Typescript Libraries to Multiple Formats | ||
|
|
||
| {% youtube | ||
| src="https://youtu.be/Vy4d0-SF5cY" | ||
| title="Packaging Typescript Lbraries" | ||
| width="100%" /%} | ||
|
|
||
| It can be difficult to set up a typescript library to compile to ESM and CommonJS. As of Nx 16.8, you can use the `@nx/rollup:rollup` executor to take care of it for you. | ||
|
|
||
| You'll need to specify `format`, `additionalEntryPoints` and `generateExportsField` in the executor options. Here's an example: | ||
|
|
||
| ```jsonc {% fileName="packages/my-awesome-lib/project.json" %} | ||
| { | ||
| "name": "my-awesome-lib", | ||
| "targets": { | ||
| "build": { | ||
| "executor": "@nx/rollup:rollup", | ||
| "options": { | ||
| "main": "packages/my-awesome-lib/src/index.ts", | ||
| "format": ["esm", "cjs"], | ||
| "additionalEntryPoints": ["packages/my-awesome-lib/src/foo.ts"], | ||
| "generateExportsField": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| After compiling our package using `nx build my-awesome-lib` we'll get the following output in our `dist` folder. | ||
|
|
||
| ``` | ||
| my-awesome-lib | ||
| └─ . | ||
| ├─ README.md | ||
| ├─ foo.cjs.d.ts | ||
| ├─ foo.cjs.js | ||
| ├─ foo.esm.js | ||
| ├─ index.cjs.d.ts | ||
| ├─ index.cjs.js | ||
| ├─ index.esm.js | ||
| ├─ package.json | ||
| └─ src | ||
| ├─ foo.d.ts | ||
| ├─ index.d.ts | ||
| └─ lib | ||
| └─ my-awesome-lib.d.ts | ||
| ``` | ||
|
|
||
| And our `package.json` will look like this: | ||
|
|
||
| ```json {% fileName="dist/my-awesome-lib/package.json" %} | ||
| { | ||
| "name": "my-awesome-lib", | ||
| "version": "0.0.1", | ||
| ... | ||
| "type": "commonjs", | ||
| "main": "./index.cjs.js", | ||
| "typings": "./src/index.d.ts", | ||
| "exports": { | ||
| "./package.json": "./package.json", | ||
| ".": { | ||
| "import": "./index.esm.js", | ||
| "default": "./index.cjs.js" | ||
| }, | ||
| "./foo": { | ||
| "import": "./foo.esm.js", | ||
| "default": "./foo.cjs.js" | ||
| } | ||
| }, | ||
| "module": "./index.esm.js" | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| Now consumers of your package can access the appropriate format for their codebase and you don't have to worry about maintaining the infrastructure to compile to both formats. |
49 changes: 49 additions & 0 deletions
49
docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| ## Define Secondary Entry Points for Typescript Packages | ||
|
|
||
| If you have a package where you want people to be able to access more than just the `main` file, you can define an `exports` property in the `package.json` file. Like this: | ||
|
|
||
| ```json {% fileName="packages/my-lib/package.json" %} | ||
| { | ||
| "exports": { | ||
| "./package.json": "./package.json", | ||
| ".": "./src/index.js", | ||
| "./foo": "./src/foo.js", | ||
| "./bar": "./src/bar.js" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Then people can access code in your library through any of the provided entry points. | ||
|
|
||
| ```ts {% fileName="some-file.ts" %} | ||
| import myLib from 'my-lib'; | ||
| import foo from 'my-lib/foo'; | ||
| import bar from 'my-lib/bar'; | ||
| ``` | ||
|
|
||
| Nx helps generate other properties in the `package.json` file, and you can also use Nx to maintain this property. | ||
|
|
||
| If you're using the `@nx/js:tsc` executor, as of Nx 16.8, you can specify the `additionalEntryPoints` and `generateExportsField` options. Here's an example: | ||
|
|
||
| ```jsonc {% fileName="packages/my-awesome-lib/project.json" %} | ||
| { | ||
| "name": "my-awesome-lib", | ||
| "targets": { | ||
| "build": { | ||
| "executor": "@nx/js:tsc", | ||
| "options": { | ||
| "main": "packages/my-awesome-lib/src/index.ts", | ||
| "additionalEntryPoints": [ | ||
| "packages/my-awesome-lib/src/foo.ts", | ||
| "packages/my-awesome-lib/src/bar.ts" | ||
| ], | ||
| "generateExportsField": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| When building the library, the `@nx/js:tsc` executor automatically adds the correct `exports` definition to the resulting `package.json`. | ||
|
|
||
| You can also [compile to multiple formats](/recipes/tips-n-tricks/compile-multiple-formats), if you switch to using the `@nx/rollup:rollup` executor. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
51d2facThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Successfully deployed to the following URLs:
nx-dev – ./
nx-five.vercel.app
nx-dev-git-master-nrwl.vercel.app
nx-dev-nrwl.vercel.app
nx.dev