feat: monorepo handling (#434)

* feat: monorepo handling

* chore: move demo to use monorepo features

* feat: add Nx config checks

* chore: fix tests

* Remove log

Co-authored-by: lindsaylevine <[email protected]>

* chore: changes from review

* fix: handle next imports

* fix: sort out require handling

* chore: add todo for documenting monorepo in error message

* chore: add docs

* chore: add links to error messages

* chore: set targetPort in nx doc

Co-authored-by: lindsaylevine <[email protected]>

Author: ascorbic

.gitignore

@@ -150,3 +150,5 @@ Temporary Items
 
 # End of https://www.toptal.com/developers/gitignore/api/osx,node
 demo/package-lock.json
+
+.netlify

README.md

@@ -77,6 +77,7 @@ Read more about [file-based plugin installation](https://docs.netlify.com/config
 - [CLI Usage](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/cli-usage.md)
 - [Custom Netlify Functions](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/custom-functions.md)
 - [Image Handling](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/image-handling.md)
+- [Monorepos and Nx](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/monorepos.md)
 - [Custom Netlify Redirects](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/custom-redirects.md)
 - [Local Files in Runtime](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/local-files-in-runtime.md)
 - [FAQ](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/faq.md)

demo/netlify.toml

@@ -0,0 +1,115 @@
+## Using in a monorepo or subdirectory
+
+The Essential Next.js plugin works in most monorepos, but may need some configuration changes. This depends on the type of monorepo and the tooling that you use.
+
+### Self-contained subdirectory
+
+If your Next.js site is in a subdirectory of the repo, but doesn't rely on installing or compiling anything outside of that directory, then the simplest arrangement is to set the `base` of the site to that directory. This can be done either in the Netlify dashboard or in the `netlify.toml`. If your site is in `/frontend`, you should set up your site with the following in the root of the repo:
+
+```toml
+# ./netlify.toml
+[build]
+  base="frontend"
+```
+You can then place another `netlify.toml` file in `/frontend/` that configures the actual build:
+
+```toml
+# ./frontend/netlify.toml
+
+[build]
+  command = "npm run build"
+  publish = "out"
+
+[[plugins]]
+  package = "@netlify/plugin-nextjs"
+```
+
+### Yarn workspace
+
+If your site is a yarn workspace - including one that uses lerna - you should keep the base as the root of the repo, but change the configuration as follows. Assuming the site is in `/packages/frontend/`:
+
+```toml
+# ./netlify.toml
+
+[build]
+  command = "next build packages/frontend"
+  publish = "packages/frontend/out"
+
+[dev]
+  command = "next dev packages/frontend"
+  
+[[plugins]]
+  package = "@netlify/plugin-nextjs"
+```
+
+Ensure that the `next.config.js` is in the site directory, i.e. `/packages/frontend/next.config.js`. You must ensure that there is either a `yarn.lock` in the root of the site, or the environment variable `NETLIFY_USE_YARN` is set to true.
+
+### Lerna monorepo using npm
+
+If your monorepo uses Yarn workspaces, then set it up as shown above in the Yarn workspace section. If it uses npm then it is a little more complicated. First, you need to ensure that the `next` package is installed as a top-level dependency, i.e. it is in `./package.json` rather than `packages/frontend/package.json`. This is because it needs to be installed before lerna is bootstrapped as the build plugin needs to use it. Generally, hoisting as many packages to the top level as possible is best, so that they are more efficiently cached. You then should change the build command, and make it similar to this:
+
+```toml
+# ./netlify.toml
+
+[build]
+  command = "lerna bootstrap && next build packages/frontend"
+  publish = "packages/frontend/out"
+
+[dev]
+  command = "next dev packages/frontend"
+  
+[[plugins]]
+  package = "@netlify/plugin-nextjs"
+```
+
+### Nx
+
+[Nx](https://nx.dev/) is a build framework that handles scaffolding, building and deploying projects. It has support for Next.js via the `@nrwl/next` package. When building a Next.js site, it changes a lot of the configuraiton on the fly, and has quite a different directory structure to a normal Next.js site. The Essential Next.js plugin has full support for sites that use Nx, but there are a few required changes that you must make to the configuration.
+
+First, you need to make the `publish` directory point at a dirctory called `out` inside the app directory, rather than the build directory. If your app is called `myapp`, your `netlify.toml` should look something like:
+
+```toml
+# ./netlify.toml
+
+[build]
+  command = "npm run build"
+  publish = "apps/myapp/out"
+
+[dev]
+  command = "npm run start"
+  targetPort = 4200
+  
+[[plugins]]
+  package = "@netlify/plugin-nextjs"
+```
+
+You also need to make a change to the `next.config.js` inside the app directory. By default, Nx changes the Next.js `distDir` on the fly, changing it to a directory in the root of the repo. The Essential Next.js plugin can't read this value, so has no way of determining where the build files can be found. However, if you change the `distDir` in the config to anything except `.next`, then `Nx` will leave it unchanged, and the Essential Next.js plugin can read the value from there. e.g. 
+
+```js
+// ./apps/myapp/next.config.js
+
+const withNx = require('@nrwl/next/plugins/with-nx');
+
+module.exports = withNx({
+  distDir: '.dist',
+  target: 'serverless'
+});
+
+```
+
+### Other monorepos
+
+Other arrangements may work: for more details, see [the monorepo documentation](https://docs.netlify.com/configure-builds/common-configurations/monorepos/). The important points are:
+
+1. The `next` package must be installed as part of the initial `npm install` or `yarn install`, not from the build command.
+2. The `publish` directory must be called `out`, and should be in the same directory as the `next.config.js` file. e.g.
+   
+   ```
+   backend/
+   frontend/
+           |- next.config.js
+           |- out
+   netlify.toml 
+   package.json
+   ```
+If you have another monorepo tool that you are using, we would welcome PRs to add instructions to this document.

demo/package.json

@@ -0,0 +1,55 @@
+const { existsSync } = require('fs')
+const { EOL } = require('os')
+const path = require('path')
+
+const checkNxConfig = ({ netlifyConfig, nextConfig, failBuild, constants: { PUBLISH_DIR } }) => {
+  const errors = []
+  if (nextConfig.distDir === '.next') {
+    errors.push(
+      "- When using Nx you must set a value for 'distDir' in your next.config.js, and the value cannot be '.next'",
+    )
+  }
+  // The PUBLISH_DIR constant is normalized, so no leading slash is needed
+  if (!PUBLISH_DIR.startsWith('apps/')) {
+    errors.push(
+      "Please set the 'publish' value in your Netlify build config to a folder inside your app directory. e.g. 'apps/myapp/out'",
+    )
+  }
+  // Look for the config file as a sibling of the publish dir
+  const expectedConfigFile = path.resolve(netlifyConfig.build.publish, '..', 'next.config.js')
+
+  if (expectedConfigFile !== nextConfig.configFile) {
+    const confName = path.relative(process.cwd(), nextConfig.configFile)
+    errors.push(
+      `- Using incorrect config file '${confName}'. Expected to use '${path.relative(
+        process.cwd(),
+        expectedConfigFile,
+      )}'`,
+    )
+
+    if (existsSync(expectedConfigFile)) {
+      errors.push(
+        `Please move or delete '${confName}'${confName === 'next.config.js' ? ' from the root of your site' : ''}.`,
+      )
+    } else {
+      errors.push(
+        `Please move or delete '${confName}'${
+          confName === 'next.config.js' ? ' from the root of your site' : ''
+        }, and create '${path.relative(process.cwd(), expectedConfigFile)}' instead.`,
+      )
+    }
+  }
+
+  if (errors.length !== 0) {
+    failBuild(
+      // TODO: Add ntl.fyi link to docs
+      [
+        'Invalid configuration',
+        ...errors,
+        'See the docs on using Nx with Netlify for more information: https://ntl.fyi/nx-next',
+      ].join(EOL),
+    )
+  }
+}
+
+module.exports = checkNxConfig

docs/monorepos.md

@@ -1,5 +1,3 @@
-const findUp = require('find-up')
-
 // Checks all the cases for which the plugin should do nothing
 const doesSiteUseNextOnNetlify = require('./doesSiteUseNextOnNetlify')
 const isStaticExportProject = require('./isStaticExportProject')

helpers/checkNxConfig.js

@@ -4,13 +4,17 @@ const { cwd: getCwd } = require('process')
 
 const moize = require('moize')
 
+const resolveNextModule = require('./resolveNextModule')
+
 // We used to cache nextConfig for any cwd. Now we pass process.cwd() to cache
 // (or memoize) nextConfig per cwd.
 const getNextConfig = async function (failBuild = defaultFailBuild, cwd = getCwd()) {
   // We cannot load `next` at the top-level because we validate whether the
   // site is using `next` inside `onPreBuild`.
-  const { PHASE_PRODUCTION_BUILD } = require('next/constants')
-  const loadConfig = require('next/dist/next-server/server/config').default
+  /* eslint-disable import/no-dynamic-require */
+  const { PHASE_PRODUCTION_BUILD } = require(resolveNextModule('next/constants', cwd))
+  const loadConfig = require(resolveNextModule('next/dist/next-server/server/config', cwd)).default
+  /* eslint-enable import/no-dynamic-require */
 
   try {
     return await loadConfig(PHASE_PRODUCTION_BUILD, cwd)

helpers/doesNotNeedPlugin.js

@@ -0,0 +1,16 @@
+const { existsSync } = require('fs')
+const path = require('path')
+
+/**
+ * If we're in a monorepo then the Next root may not be the same as the base directory
+ * If there's no next.config.js in the root, we instead look for it as a sibling of the publish dir
+ */
+const getNextRoot = ({ netlifyConfig }) => {
+  let nextRoot = process.cwd()
+  if (!existsSync(path.join(nextRoot, 'next.config.js')) && netlifyConfig.build.publish) {
+    nextRoot = path.dirname(netlifyConfig.build.publish)
+  }
+  return nextRoot
+}
+
+module.exports = getNextRoot

helpers/getNextConfig.js

@@ -0,0 +1,13 @@
+/**
+ * We can't require() these normally, because the "next" package might not be resolvable from the root of a monorepo
+ */
+const resolveNextModule = (module, nextRoot) => {
+  // Get the default list of require paths...
+  const paths = require.resolve.paths(module)
+  // ...add the root of the Next site to the beginning of that list so we try it first...
+  paths.unshift(nextRoot)
+  // ...then resolve the module using that list of paths.
+  return require.resolve(module, { paths })
+}
+
+module.exports = resolveNextModule