Next.js Plugin

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 Next.js

To create a new Nx workspace with Next.js, run npx create-nx-workspace@latest --preset=next.

To add Next.js to an existing Nx workspace, install the @nrwl/next package. Make sure to install the version that matches your @nrwl/workspace version.

#yarn
yarn add --dev @nrwl/next

#npm
npm install --save-dev @nrwl/next

Creating Applications

You can add a new application with the following:

nx g @nrwl/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 @nrwl/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 @nrwl/next:page my-new-page --project=my-new-app

nx g @nrwl/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 run nx serve my-new-app to serve a Next.js application called my-new-app for development. This will start the dev server at http://localhost:4200.

To serve a Next.js application for production, add the --prod flag to the serve command:

nx serve my-new-app --prod

Using an Nx Library in your Application

You can import a library called my-new-lib in your application as follows.

1// apps/my-next-app/pages/index.tsx
2import { MyNewLib } from '@<your nx workspace name>/my-new-lib';
3
4export function Index() {
5  return (
6    <MyNewLib>
7      <p>The main content</p>
8    </MyNewLib>
9  );
10}
11
12export default Index;

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 @nrwl/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 with:

nx export my-new-app

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.