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 Sync

Make 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:

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.js
  • next.config.cjs
  • next.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.

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
Nx 15 and lower use @nrwl/ instead of @nx/
  • The buildTargetName option controls the name of Next.js' compilation task which compiles the application for production deployment. The default name is build.
  • The devTargetName option controls the name of Next.js' development serve task which starts the application in development mode. The default name is dev.
  • The startTargetName option controls the name of Next.js' production serve task which starts the application in production mode. The default name is start.

Using @nx/next

Creating Applications

You can add a new application with the following:

❯

nx g @nx/next:app my-new-app

Nx 15 and lower use @nrwl/ instead of @nx/

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

Nx 15 and lower use @nrwl/ instead of @nx/

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

Nx 15 and lower use @nrwl/ instead of @nx/

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.

apps/my-next-app/pages/index.tsx
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; 12

There 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

Nx 15 and lower use @nrwl/ instead of @nx/

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.

apps/my-next-app/next.config.js
1const nextConfig = { 2 output: 'export', 3 nx: { 4 svgr: false, 5 }, 6}; 7

Deploying 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.