docs(core): add typescript packaging recipes (#19262)

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",

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",

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",

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.

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.

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)