docs(nextjs): add a guide for configuring Next.js plugins (nrwl#16315)

docs/generated/manifests/menus.json

@@ -5101,6 +5101,14 @@
                 "isExternal": false,
                 "children": [],
                 "disableCollapsible": false
+              },
+              {
+                "name": "How to configure Next.js plugins",
+                "path": "/packages/next/documents/next-config-setup",
+                "id": "next-config-setup",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
               }
             ],
             "isExternal": false,

docs/generated/manifests/packages.json

@@ -1281,7 +1281,18 @@
         "isExternal": false,
         "path": "/packages/next/documents/overview",
         "tags": [],
-        "originalFilePath": "shared/packages/next/next-plugin"
+        "originalFilePath": "shared/packages/next/plugin-overview"
+      },
+      "/packages/next/documents/next-config-setup": {
+        "id": "next-config-setup",
+        "name": "How to configure Next.js plugins",
+        "description": "A guide for configuring Next.js plugins with Nx",
+        "file": "generated/packages/next/documents/next-config-setup",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/packages/next/documents/next-config-setup",
+        "tags": [],
+        "originalFilePath": "shared/packages/next/next-config-setup"
       }
     },
     "root": "/packages/next",

docs/generated/packages-metadata.json

@@ -1264,7 +1264,18 @@
         "isExternal": false,
         "path": "next/documents/overview",
         "tags": [],
-        "originalFilePath": "shared/packages/next/next-plugin"
+        "originalFilePath": "shared/packages/next/plugin-overview"
+      },
+      {
+        "id": "next-config-setup",
+        "name": "How to configure Next.js plugins",
+        "description": "A guide for configuring Next.js plugins with Nx",
+        "file": "generated/packages/next/documents/next-config-setup",
+        "itemList": [],
+        "isExternal": false,
+        "path": "next/documents/next-config-setup",
+        "tags": [],
+        "originalFilePath": "shared/packages/next/next-config-setup"
       }
     ],
     "executors": [

docs/generated/packages/next/documents/next-config-setup.md

@@ -0,0 +1,112 @@
+---
+title: How to configure Next.js plugins
+description: A guide for configuring Next.js plugins with Nx
+---
+
+# Configuring Next.js plugins
+
+Next.js plugins are configured in the project's `next.config.js` file. Nx adds a its own plugin (`withNx`) to help the Next.js application
+understand workspace libraries, and other Nx-specific features. See below for an example of the `withNx` plugin that Nx adds by default.
+
+```js
+// next.config.js
+
+// ...
+
+module.exports = withNx({
+  // Nx configuration goes here
+  nx: {
+    svgr: false,
+  },
+  // Add Next.js configuration goes here
+});
+```
+
+This guide contains information on how to compose the Nx plugin with other plugins, such as `@next/mdx`. Note that Nx prior to version 16 is missing the compose utility from the `@nrwl/next` package, and a workaround will be provided for Nx 15 and prior.
+
+{% callout type="warning" title="Avoid next-compose-plugins" %}
+There is a popular package called `next-compose-plugins` that has not been maintained for over two years. This package does not correctly combine plugins in all situations. If you do use it, replace the package with Nx 16's `composePlugins` utility (see below).
+{% /callout %}
+
+## Composing plugins using `composePlugins` utility (Nx 16 and later)
+
+Since Nx 16, we provide a `composePlugins` utility function that helps users combine multiple Next.js plugins together.
+
+```js
+// next.config.js
+const { composePlugins, withNx } = require('@nrwl/next');
+/**
+ * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions}
+ **/
+const nextConfig = {
+  nx: {
+    // Set this to true if you would like to to use SVGR
+    // See: https://github.com/gregberge/svgr
+    svgr: false,
+  },
+  // Add Next.js configuration here
+};
+
+const plugins = [
+  // Add more Next.js plugins to this list if needed.
+  withNx,
+];
+
+module.exports = composePlugins(...plugins)(nextConfig);
+```
+
+If you want to add additional plugins, say [`@next/mdx`](https://www.npmjs.com/package/@next/mdx), you can add it to the plugins list.
+
+```js
+const plugins = [
+  // Add more Next.js plugins to this list if needed.
+  require('@next/mdx')(),
+  withNx,
+];
+
+module.exports = composePlugins(...plugins)(nextConfig);
+```
+
+This the exported configuration will correctly call each plugin in order and apply their configuration changes to the final object. Note that `composePlugins` function will return an async function, so if you need to debug the configuration you can add a debug plugin as follows.
+
+```js
+module.exports = composePlugins(...plugins, function debug(config) {
+  // The debug plugin will be called last
+  console.log({ config });
+  return config;
+})(nextConfig);
+```
+
+## Manually composing plugins (Nx 15 and prior)
+
+If you are not on Nx 16 and later versions, the `composePlugins` utility is not available. However, you can use the workaround below to use multiple plugins.
+
+```js
+// next.config.js
+
+// ...
+
+/**
+ * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions}
+ **/
+const nextConfig = {
+  // ...
+};
+
+const plugins = [
+  // Your plugins exlcuding withNx
+];
+
+module.exports = async (phase, context) => {
+  let updatedConfig = plugins.reduce((acc, fn) => fn(acc), nextConfig);
+
+  // Apply the async function that `withNx` returns.
+  updatedConfig = await withNx(updatedConfig)(phase, context);
+
+  // If you have plugins that has to be added after Nx you can do that here.
+  // For example, Sentry needs to be added last.
+  updatedConfig = require('@sentry/nextjs')(updatedConfig, { silent: true });
+
+  return updatedConfig;
+};
+```

docs/map.json

@@ -2007,7 +2007,13 @@
               "id": "overview",
               "name": "Overview",
               "path": "/packages/next",
-              "file": "shared/packages/next/next-plugin"
+              "file": "shared/packages/next/plugin-overview"
+            },
+            {
+              "id": "next-config-setup",
+              "name": "How to configure Next.js plugins",
+              "description": "A guide for configuring Next.js plugins with Nx",
+              "file": "shared/packages/next/next-config-setup"
             }
           ]
         },

docs/shared/packages/next/next-config-setup.md

@@ -0,0 +1,112 @@
+---
+title: How to configure Next.js plugins
+description: A guide for configuring Next.js plugins with Nx
+---
+
+# Configuring Next.js plugins
+
+Next.js plugins are configured in the project's `next.config.js` file. Nx adds a its own plugin (`withNx`) to help the Next.js application
+understand workspace libraries, and other Nx-specific features. See below for an example of the `withNx` plugin that Nx adds by default.
+
+```js
+// next.config.js
+
+// ...
+
+module.exports = withNx({
+  // Nx configuration goes here
+  nx: {
+    svgr: false,
+  },
+  // Add Next.js configuration goes here
+});
+```
+
+This guide contains information on how to compose the Nx plugin with other plugins, such as `@next/mdx`. Note that Nx prior to version 16 is missing the compose utility from the `@nrwl/next` package, and a workaround will be provided for Nx 15 and prior.
+
+{% callout type="warning" title="Avoid next-compose-plugins" %}
+There is a popular package called `next-compose-plugins` that has not been maintained for over two years. This package does not correctly combine plugins in all situations. If you do use it, replace the package with Nx 16's `composePlugins` utility (see below).
+{% /callout %}
+
+## Composing plugins using `composePlugins` utility (Nx 16 and later)
+
+Since Nx 16, we provide a `composePlugins` utility function that helps users combine multiple Next.js plugins together.
+
+```js
+// next.config.js
+const { composePlugins, withNx } = require('@nrwl/next');
+/**
+ * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions}
+ **/
+const nextConfig = {
+  nx: {
+    // Set this to true if you would like to to use SVGR
+    // See: https://github.com/gregberge/svgr
+    svgr: false,
+  },
+  // Add Next.js configuration here
+};
+
+const plugins = [
+  // Add more Next.js plugins to this list if needed.
+  withNx,
+];
+
+module.exports = composePlugins(...plugins)(nextConfig);
+```
+
+If you want to add additional plugins, say [`@next/mdx`](https://www.npmjs.com/package/@next/mdx), you can add it to the plugins list.
+
+```js
+const plugins = [
+  // Add more Next.js plugins to this list if needed.
+  require('@next/mdx')(),
+  withNx,
+];
+
+module.exports = composePlugins(...plugins)(nextConfig);
+```
+
+This the exported configuration will correctly call each plugin in order and apply their configuration changes to the final object. Note that `composePlugins` function will return an async function, so if you need to debug the configuration you can add a debug plugin as follows.
+
+```js
+module.exports = composePlugins(...plugins, function debug(config) {
+  // The debug plugin will be called last
+  console.log({ config });
+  return config;
+})(nextConfig);
+```
+
+## Manually composing plugins (Nx 15 and prior)
+
+If you are not on Nx 16 and later versions, the `composePlugins` utility is not available. However, you can use the workaround below to use multiple plugins.
+
+```js
+// next.config.js
+
+// ...
+
+/**
+ * @type {import('@nrwl/next/plugins/with-nx').WithNxOptions}
+ **/
+const nextConfig = {
+  // ...
+};
+
+const plugins = [
+  // Your plugins exlcuding withNx
+];
+
+module.exports = async (phase, context) => {
+  let updatedConfig = plugins.reduce((acc, fn) => fn(acc), nextConfig);
+
+  // Apply the async function that `withNx` returns.
+  updatedConfig = await withNx(updatedConfig)(phase, context);
+
+  // If you have plugins that has to be added after Nx you can do that here.
+  // For example, Sentry needs to be added last.
+  updatedConfig = require('@sentry/nextjs')(updatedConfig, { silent: true });
+
+  return updatedConfig;
+};
+```