diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index ff03d45ca43bc..2d2c680837028 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -2249,6 +2249,22 @@ "children": [], "disableCollapsible": false }, + { + "name": "Define Secondary Entrypoints for Typescript Packages", + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "id": "define-secondary-entrypoints", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Compile Typescript Packages to Multiple Formats", + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "id": "compile-multiple-formats", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Keep Nx Versions in Sync", "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync", @@ -3678,6 +3694,22 @@ "children": [], "disableCollapsible": false }, + { + "name": "Define Secondary Entrypoints for Typescript Packages", + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "id": "define-secondary-entrypoints", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Compile Typescript Packages to Multiple Formats", + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "id": "compile-multiple-formats", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Keep Nx Versions in Sync", "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync", @@ -3841,6 +3873,22 @@ "children": [], "disableCollapsible": false }, + { + "name": "Define Secondary Entrypoints for Typescript Packages", + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "id": "define-secondary-entrypoints", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Compile Typescript Packages to Multiple Formats", + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "id": "compile-multiple-formats", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Keep Nx Versions in Sync", "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index ae29b1874065e..f5d4d45eed88f 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -2803,6 +2803,26 @@ "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode", "tags": [] }, + { + "id": "define-secondary-entrypoints", + "name": "Define Secondary Entrypoints for Typescript Packages", + "description": "", + "file": "shared/recipes/tips-n-tricks/define-secondary-entrypoints", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "tags": [] + }, + { + "id": "compile-multiple-formats", + "name": "Compile Typescript Packages to Multiple Formats", + "description": "", + "file": "shared/recipes/tips-n-tricks/compile-multiple-formats", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "tags": [] + }, { "id": "keep-nx-versions-in-sync", "name": "Keep Nx Versions in Sync", @@ -4586,6 +4606,26 @@ "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode", "tags": [] }, + { + "id": "define-secondary-entrypoints", + "name": "Define Secondary Entrypoints for Typescript Packages", + "description": "", + "file": "shared/recipes/tips-n-tricks/define-secondary-entrypoints", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "tags": [] + }, + { + "id": "compile-multiple-formats", + "name": "Compile Typescript Packages to Multiple Formats", + "description": "", + "file": "shared/recipes/tips-n-tricks/compile-multiple-formats", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "tags": [] + }, { "id": "keep-nx-versions-in-sync", "name": "Keep Nx Versions in Sync", @@ -4791,6 +4831,26 @@ "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode", "tags": [] }, + "/recipes/tips-n-tricks/define-secondary-entrypoints": { + "id": "define-secondary-entrypoints", + "name": "Define Secondary Entrypoints for Typescript Packages", + "description": "", + "file": "shared/recipes/tips-n-tricks/define-secondary-entrypoints", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/define-secondary-entrypoints", + "tags": [] + }, + "/recipes/tips-n-tricks/compile-multiple-formats": { + "id": "compile-multiple-formats", + "name": "Compile Typescript Packages to Multiple Formats", + "description": "", + "file": "shared/recipes/tips-n-tricks/compile-multiple-formats", + "itemList": [], + "isExternal": false, + "path": "/recipes/tips-n-tricks/compile-multiple-formats", + "tags": [] + }, "/recipes/tips-n-tricks/keep-nx-versions-in-sync": { "id": "keep-nx-versions-in-sync", "name": "Keep Nx Versions in Sync", diff --git a/docs/map.json b/docs/map.json index 525ed7076bd5b..2d95836030372 100644 --- a/docs/map.json +++ b/docs/map.json @@ -994,6 +994,16 @@ "id": "enable-tsc-batch-mode", "file": "shared/recipes/enable-tsc-batch-mode" }, + { + "name": "Define Secondary Entrypoints for Typescript Packages", + "id": "define-secondary-entrypoints", + "file": "shared/recipes/tips-n-tricks/define-secondary-entrypoints" + }, + { + "name": "Compile Typescript Packages to Multiple Formats", + "id": "compile-multiple-formats", + "file": "shared/recipes/tips-n-tricks/compile-multiple-formats" + }, { "name": "Keep Nx Versions in Sync", "id": "keep-nx-versions-in-sync", diff --git a/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md b/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md new file mode 100644 index 0000000000000..a017897009431 --- /dev/null +++ b/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md @@ -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. diff --git a/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md b/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md new file mode 100644 index 0000000000000..7c2136e920853 --- /dev/null +++ b/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md @@ -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. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 451aecb533557..69e68a489d2c6 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -168,6 +168,8 @@ - [Convert from a Standalone Repository to an Integrated Repository](/recipes/tips-n-tricks/standalone-to-integrated) - [Configuring ESLint with Typescript](/recipes/tips-n-tricks/eslint) - [Enable Typescript Batch Mode](/recipes/tips-n-tricks/enable-tsc-batch-mode) + - [Define Secondary Entrypoints for Typescript Packages](/recipes/tips-n-tricks/define-secondary-entrypoints) + - [Compile Typescript Packages to Multiple Formats](/recipes/tips-n-tricks/compile-multiple-formats) - [Keep Nx Versions in Sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync) - [Define Environment Variables](/recipes/tips-n-tricks/define-environment-variables) - [Configuring Browser Support](/recipes/tips-n-tricks/browser-support)