|
| 1 | +## Using in a monorepo or subdirectory |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +### Self-contained subdirectory |
| 6 | + |
| 7 | +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: |
| 8 | + |
| 9 | +```toml |
| 10 | +# ./netlify.toml |
| 11 | +[build] |
| 12 | + base="frontend" |
| 13 | +``` |
| 14 | +You can then place another `netlify.toml` file in `/frontend/` that configures the actual build: |
| 15 | + |
| 16 | +```toml |
| 17 | +# ./frontend/netlify.toml |
| 18 | + |
| 19 | +[build] |
| 20 | + command = "npm run build" |
| 21 | + publish = "out" |
| 22 | + |
| 23 | +[[plugins]] |
| 24 | + package = "@netlify/plugin-nextjs" |
| 25 | +``` |
| 26 | + |
| 27 | +### Yarn workspace |
| 28 | + |
| 29 | +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/`: |
| 30 | + |
| 31 | +```toml |
| 32 | +# ./netlify.toml |
| 33 | + |
| 34 | +[build] |
| 35 | + command = "next build packages/frontend" |
| 36 | + publish = "packages/frontend/out" |
| 37 | + |
| 38 | +[dev] |
| 39 | + command = "next dev packages/frontend" |
| 40 | + |
| 41 | +[[plugins]] |
| 42 | + package = "@netlify/plugin-nextjs" |
| 43 | +``` |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +### Lerna monorepo using npm |
| 48 | + |
| 49 | +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: |
| 50 | + |
| 51 | +```toml |
| 52 | +# ./netlify.toml |
| 53 | + |
| 54 | +[build] |
| 55 | + command = "lerna bootstrap && next build packages/frontend" |
| 56 | + publish = "packages/frontend/out" |
| 57 | + |
| 58 | +[dev] |
| 59 | + command = "next dev packages/frontend" |
| 60 | + |
| 61 | +[[plugins]] |
| 62 | + package = "@netlify/plugin-nextjs" |
| 63 | +``` |
| 64 | + |
| 65 | +### Nx |
| 66 | + |
| 67 | +[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. |
| 68 | + |
| 69 | +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: |
| 70 | + |
| 71 | +```toml |
| 72 | +# ./netlify.toml |
| 73 | + |
| 74 | +[build] |
| 75 | + command = "npm run build" |
| 76 | + publish = "apps/myapp/out" |
| 77 | + |
| 78 | +[dev] |
| 79 | + command = "npm run start" |
| 80 | + targetPort = 4200 |
| 81 | + |
| 82 | +[[plugins]] |
| 83 | + package = "@netlify/plugin-nextjs" |
| 84 | +``` |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +```js |
| 89 | +// ./apps/myapp/next.config.js |
| 90 | + |
| 91 | +const withNx = require('@nrwl/next/plugins/with-nx'); |
| 92 | + |
| 93 | +module.exports = withNx({ |
| 94 | + distDir: '.dist', |
| 95 | + target: 'serverless' |
| 96 | +}); |
| 97 | + |
| 98 | +``` |
| 99 | + |
| 100 | +### Other monorepos |
| 101 | + |
| 102 | +Other arrangements may work: for more details, see [the monorepo documentation](https://docs.netlify.com/configure-builds/common-configurations/monorepos/). The important points are: |
| 103 | + |
| 104 | +1. The `next` package must be installed as part of the initial `npm install` or `yarn install`, not from the build command. |
| 105 | +2. The `publish` directory must be called `out`, and should be in the same directory as the `next.config.js` file. e.g. |
| 106 | + |
| 107 | + ``` |
| 108 | + backend/ |
| 109 | + frontend/ |
| 110 | + |- next.config.js |
| 111 | + |- out |
| 112 | + netlify.toml |
| 113 | + package.json |
| 114 | + ``` |
| 115 | +If you have another monorepo tool that you are using, we would welcome PRs to add instructions to this document. |
0 commit comments