Nx with Next.js

Nx helps you organize a Next.js monorepo where apps and shared libraries live side by side. The Next.js plugin for Nx, @nx/next, automatically infers build, dev, and start tasks from your Next.js configuration and provides generators for creating applications and libraries.

You don't need the plugin to use Next.js with Nx. Any project already benefits from caching, task orchestration, and the project graph. The plugin adds automatic task inference, code generators, and simplified configuration.

Requirements

The @nx/next plugin supports the following package versions.

Package	Supported Versions
next	>=15.0.0 <17.0.0

Nx generators install the latest supported versions automatically when scaffolding new projects.

Setting up @nx/next

Add to an existing Nx workspace

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. Using nx add helps ensure the correct version is installed and configured.

nx add @nx/next

Verify the plugin is setup:

1. Check for @nx/next listed as a plugin:

   nx report

2. Ensure inferred project targets are working:

   nx show projects --with-target=build

3. Inspect a specific project configuration:

   nx show project my-next-app

Create a new workspace

Start from the Next.js template to scaffold a Next.js app with a shared UI library:

npx create-nx-workspace@latest my-workspace --template nrwl/nextjs-template

Generate a new application

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

To start the application in development mode, run nx dev my-app. Read more about the options available for the application generator.

Generate a library

nx g @nx/next:lib libs/my-lib

# For a publishable library
nx g @nx/next:lib libs/my-lib --publishable --importPath=@myorg/my-lib

Read more about the options available for the library generator.

Develop Next.js applications

Serve for development

nx dev my-app

Starts the Next.js development server at http://localhost:3000 by default.

Build for production

nx build my-app

The output goes to the .next folder inside your app's project directory by default. Customize the output directory with distDir in your next.config.js:

apps/my-app/next.config.js

const nextConfig = {
  distDir: 'dist',
};

module.exports = nextConfig;

Start production server

nx start my-app

Serves the production build. Depends on build completing first.

Use libraries in your application

apps/my-app/pages/index.tsx

import { MyComponent } from '@myorg/my-lib';

export default function Index() {
  return <MyComponent />;
}

There is no need to build the library prior to using it. When you update your library, the Next.js application automatically picks up the changes.

Configure @nx/next

How @nx/next infers tasks

The @nx/next plugin creates tasks for any project that has a Next.js configuration file. Any of the following files are recognized:

• next.config.js
• next.config.cjs
• next.config.mjs
• next.config.ts

Plugin options

Configure @nx/next/plugin in the plugins array in nx.json:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/next/plugin",
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}

Option	Description	Default
buildTargetName	Name of the production build task	build
devTargetName	Name of the development server task	dev
startTargetName	Name of the production server task	start
serveStaticTargetName	Name of the static export serve task	serve-static

Exclude or include specific projects

Use include/exclude glob patterns in the plugin configuration to scope which projects the plugin applies to:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/next/plugin",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}

View inferred tasks

To see what tasks Nx inferred for a project:

nx show project my-app

Or open the project details view in Nx Console.

Set up CI for your Next.js monorepo

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.

What's next

Deploy Next.js to Vercel Deploy your Next.js application to Vercel with Nx.

Next.js Config Setup Configure Next.js settings for your Nx workspace.

Learn Nx Tutorial Build a monorepo step-by-step with Nx.

Generators Reference Full API reference for @nx/next generators.

Executors Reference Full API reference for @nx/next executors.

Migrations Reference Full reference for @nx/next migrations.