From b6ea9cd305cbd33d81e65f204c75d4c3808db7d1 Mon Sep 17 00:00:00 2001
From: Juri Strumpflohner <juri.strumpflohner@gmail.com>
Date: Tue, 21 Nov 2023 19:06:27 +0100
Subject: [PATCH] docs(js): improve secondary entry point and multiple format
 docs (#20350)

---
 .../tips-n-tricks/compile-multiple-formats.md | 59 ++++++++++++++++++-
 .../define-secondary-entrypoints.md           | 38 +++++++++++-
 2 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md b/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md
index a017897009431..4a67b73701ccf 100644
--- a/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md
+++ b/docs/shared/recipes/tips-n-tricks/compile-multiple-formats.md
@@ -1,4 +1,4 @@
-## Compile Typescript Libraries to Multiple Formats
+# Compile Typescript Libraries to Multiple Formats
 
 {% youtube
 src="https://youtu.be/Vy4d0-SF5cY"
@@ -7,9 +7,64 @@ 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:
+## Use Rollup to Compile your TypeScript Project
+
+If you do not use Rollup already, install the corresponding Nx plugin as follows:
+
+```shell
+npm i @nx/rollup
+```
+
+Make sure the version of `@nx/rollup` matches your other `@nx/*` package versions.
+
+You can then configure Rollup to compile your library by adding a `build` target to your `project.json` or `package.json` file. Here's an example:
+
+{% tabs %}
+{%tab label="package.json"%}
+
+```jsonc {% fileName="packages/my-awesome-lib/project.json" %}
+{
+  "name": "my-awesome-lib",
+  "nx": {
+    "targets": {
+      "build": {
+        "executor": "@nx/rollup:rollup",
+        "options": {
+          "main": "packages/my-awesome-lib/src/index.ts"
+        }
+      }
+    }
+  }
+}
+```
+
+{% /tab%}
+{%tab label="project.json"%}
 
 ```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"
+      }
+    }
+  }
+}
+```
+
+{% /tab%}
+{% /tabs %}
+
+If you happen to use the `@nx/js:tsc` executor already, you can also use the [Rollup configuration](/nx-api/rollup/generators/configuration) generator from the Nx Rollup plugin to automatically configure your project's build target.
+
+## Configure Rollup to Create Multiple Formats
+
+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" highlightLines=["8-10"] %}
 {
   "name": "my-awesome-lib",
   "targets": {
diff --git a/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md b/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md
index 7c2136e920853..2fdf9321706c8 100644
--- a/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md
+++ b/docs/shared/recipes/tips-n-tricks/define-secondary-entrypoints.md
@@ -1,4 +1,4 @@
-## Define Secondary Entry Points for Typescript Packages
+# 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:
 
@@ -21,10 +21,39 @@ import foo from 'my-lib/foo';
 import bar from 'my-lib/bar';
 ```
 
+## Setup package.json export fields with Nx
+
 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:
 
+{% tabs %}
+{%tab label="package.json"%}
+
+```jsonc {% fileName="packages/my-awesome-lib/package.json" %}
+{
+  "name": "my-awesome-lib",
+  "nx": {
+    "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
+        }
+      }
+    }
+  }
+}
+```
+
+{% /tab%}
+{%tab label="project.json"%}
+
 ```jsonc {% fileName="packages/my-awesome-lib/project.json" %}
 {
   "name": "my-awesome-lib",
@@ -44,6 +73,11 @@ If you're using the `@nx/js:tsc` executor, as of Nx 16.8, you can specify the `a
 }
 ```
 
+{% /tab%}
+{% /tabs %}
+
 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.
+## Compile to Multiple Formats
+
+You can also compile to multiple formats, if you switch to using the `@nx/rollup:rollup` executor. Read all [the details here](/recipes/tips-n-tricks/compile-multiple-formats).