From 622883294e03166f6e8433d3e685079f0e5f76c4 Mon Sep 17 00:00:00 2001 From: Jack Hsu Date: Tue, 18 Apr 2023 08:58:04 -0400 Subject: [PATCH] docs(nextjs): add a guide for configuring Next.js plugins (#16315) --- docs/generated/manifests/menus.json | 8 ++ docs/generated/manifests/packages.json | 13 +- docs/generated/packages-metadata.json | 13 +- .../next/documents/next-config-setup.md | 112 ++++++++++++++++++ docs/map.json | 8 +- .../shared/packages/next/next-config-setup.md | 112 ++++++++++++++++++ .../{next-plugin.md => plugin-overview.md} | 0 7 files changed, 263 insertions(+), 3 deletions(-) create mode 100644 docs/generated/packages/next/documents/next-config-setup.md create mode 100644 docs/shared/packages/next/next-config-setup.md rename docs/shared/packages/next/{next-plugin.md => plugin-overview.md} (100%) diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 128975e487624e..29cea308c1a732 100644 --- a/docs/generated/manifests/menus.json +++ b/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, diff --git a/docs/generated/manifests/packages.json b/docs/generated/manifests/packages.json index 0c2ca9e99dcd5d..7f59d6116e8b53 100644 --- a/docs/generated/manifests/packages.json +++ b/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", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index 297d4fa1ee4c05..037f6518e19d8f 100644 --- a/docs/generated/packages-metadata.json +++ b/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": [ diff --git a/docs/generated/packages/next/documents/next-config-setup.md b/docs/generated/packages/next/documents/next-config-setup.md new file mode 100644 index 00000000000000..b03835294f1ae1 --- /dev/null +++ b/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; +}; +``` diff --git a/docs/map.json b/docs/map.json index 5346792d787eeb..3144be704c4104 100644 --- a/docs/map.json +++ b/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" } ] }, diff --git a/docs/shared/packages/next/next-config-setup.md b/docs/shared/packages/next/next-config-setup.md new file mode 100644 index 00000000000000..b03835294f1ae1 --- /dev/null +++ b/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; +}; +``` diff --git a/docs/shared/packages/next/next-plugin.md b/docs/shared/packages/next/plugin-overview.md similarity index 100% rename from docs/shared/packages/next/next-plugin.md rename to docs/shared/packages/next/plugin-overview.md