When using Next.js in Nx, you get the out-of-the-box support for TypeScript, Cypress, and Jest. No need to configure anything: watch mode, source maps, and typings just work.
The Next.js plugin contains executors and generators for managing Next.js applications and libraries within an Nx workspace. It provides:
- Scaffolding for creating, building, serving, linting, and testing Next.js applications.
- Integration with building, serving, and exporting a Next.js application.
- Integration with React libraries within the workspace.
Setting up @nx/next
To create a new Nx workspace with Next.js, run:
❯
npx create-nx-workspace@latest --preset=next
Installation
Keep Nx Package Versions In SyncMake sure to install the @nx/next version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe.
In any workspace, you can install @nx/next by running the following command:
❯
nx add @nx/next
This will install the correct version of @nx/next.
How @nx/next Infers Tasks
The @nx/next plugin will create tasks for any project that has a Next.js configuration file preset. Any of the following files will be recognized as a Next.js configuration file:
next.config.jsnext.config.cjsnext.config.mjs
View Inferred Tasks
To view inferred tasks for a project, open the project details view in Nx Console or run nx show project <project-name> --web in your command line.
@nx/next Configuration
The @nx/next/plugin is configured in the plugins array in nx.json.
1{
2 "plugins": [
3 {
4 "plugin": "@nx/next/plugin",
5 "options": {
6 "buildTargetName": "build",
7 "devTargetName": "dev",
8 "startTargetName": "start"
9 }
10 }
11 ]
12}
13- The
buildTargetNameoption controls the name of Next.js' compilation task which compiles the application for production deployment. The default name isbuild. - The
devTargetNameoption controls the name of Next.js' development serve task which starts the application in development mode. The default name isdev. - The
startTargetNameoption controls the name of Next.js' production serve task which starts the application in production mode. The default name isstart.
Using @nx/next
Creating Applications
You can add a new application with the following:
❯
nx g @nx/next:app my-new-app
Generating Libraries
Nx allows you to create libraries with just one command. Some reasons you might want to create a library include:
- Share code between applications
- Publish a package to be used outside the monorepo
- Better visualize the architecture using
nx graph
For more information on Nx libraries, see our documentation on Creating Libraries and Library Types.
To generate a new library run:
❯
nx g @nx/next:lib my-new-lib
Generating Pages and Components
Nx also provides commands to quickly generate new pages and components for your application.
❯
nx g @nx/next:page my-new-page --project=my-new-app
❯
nx g @nx/next:component my-new-component --project=my-new-app
Above commands will add a new page my-new-page and a component my-new-component to my-new-app project respectively.
Nx generates components with tests by default. For pages, you can pass the --withTests option to generate tests under the specs folder.
Using Next.js
Serving Next.js Applications
You can serve a Next.js application my-new-app for development:
❯
nx dev my-new-app
To serve a Next.js application for production:
❯
nx start my-new-app
This will start the server at http://localhost:3000 by default.
Using an Nx Library in your Application
You can import a library called my-new-lib in your application as follows.
1import { MyNewLib } from '@<your nx workspace name>/my-new-lib';
2
3export function Index() {
4 return (
5 <MyNewLib>
6 <p>The main content</p>
7 </MyNewLib>
8 );
9}
10
11export default Index;
12There is no need to build the library prior to using it. When you update your library, the Next.js application will automatically pick up the changes.
Publishable libraries
For libraries intended to be built and published to a registry (e.g. npm) you can use the --publishable and --importPath options.
❯
nx g @nx/next:lib my-new-lib --publishable --importPath=@happynrwl/ui-components
Testing Projects
You can run unit tests with:
❯
nx test my-new-app
❯
nx test my-new-lib
Replace my-new-app and my-new-lib with the name or the project you want to test. This command works for both applications and libraries.
You can also run E2E tests for applications:
❯
nx e2e my-new-app-e2e
Replace my-new-app-e2e with the name or your project with -e2e appended.
Linting Projects
You can lint projects with:
❯
nx lint my-new-app
❯
nx lint my-new-lib
Replace my-new-app and my-new-lib with the name or the project you want to test. This command works for both applications and libraries.
Building Projects
Next.js applications can be build with:
❯
nx build my-new-app
And if you generated a library with --buildable, then you can build a library as well:
❯
nx build my-new-lib
After running a build, the output will be in the dist folder. You can customize the output folder by setting outputPath in the project's project.json file.
The library in dist is publishable to npm or a private registry.
Static HTML Export
Next.js applications can be statically exported by changing the output inside your Next.js configuration file.
1const nextConfig = {
2 output: 'export',
3 nx: {
4 svgr: false,
5 },
6};
7Deploying Next.js Applications
Once you are ready to deploy your Next.js application, you have absolute freedom to choose any hosting provider that fits your needs.
You may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed how to deploy your Next.js application to Vercel in a separate guide.
More Documentation
Here are other resources that you may find useful to learn more about Next.js and Nx.
- Blog post: Building a blog with Next.js and Nx Series by Juri Strumpflohner
- Video tutorial: Typescript NX Monorepo with NextJS and Express by Jack Herrington