@nx/next

The Next.js plugin for Nx provides generators and executors for managing Next.js applications within an Nx workspace.

The @nx/next plugin integrates Next.js into your Nx workspace. It provides generators for scaffolding full applications, pages, and components, along with dedicated executors for building and serving Next.js apps. TypeScript, Playwright, Cypress, and Jest support are included with no extra configuration.

Installation

nx add @nx/next

Or install manually:

npm

npm install --save-dev @nx/next

@nx/next requires next 14.x or 15.x/16.x as a peer dependency. Install it alongside this plugin: npm install next react react-dom.

What the plugin provides

Generators

Scaffold Next.js applications, pages, components, and libraries. Includes custom server setup.

Executors

Dedicated build and server executors purpose-built for Next.js production builds and development serving.

Inferred tasks

Automatically infers build, serve, and start targets from your Next.js config file.

Generators

application

Create a new Next.js application.

nx generate @nx/next:application myapp

Choose your end-to-end testing setup:

# With Playwright
nx generate @nx/next:application myapp --e2eTestRunner=playwright

# With Cypress
nx generate @nx/next:application myapp --e2eTestRunner=cypress

# No e2e runner
nx generate @nx/next:application myapp --e2eTestRunner=none

page

Create a new page inside an existing Next.js application.

nx generate @nx/next:page about --project=myapp --directory=app

component

Generate a React component within a Next.js project.

nx generate @nx/next:component Header --project=myapp

library

Create a shared library that can be imported by your Next.js application and other workspace projects.

nx generate @nx/next:library ui-components

custom-server

Add a custom Express-based server to a Next.js application.

nx generate @nx/next:custom-server --project=myapp

convert-to-inferred

Migrate an existing Next.js project from using the @nx/next:build executor to using the inferred task plugin (@nx/next/plugin).

nx generate @nx/next:convert-to-inferred

# Migrate a single project
nx generate @nx/next:convert-to-inferred --project=myapp

Executors

build

Build a Next.js application for production. Runs next build under the hood.

{
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "options": {
        "root": "myapp",
        "outputPath": "dist/myapp"
      },
      "configurations": {
        "production": {
          "debug": false
        },
        "development": {
          "debug": true
        }
      },
      "defaultConfiguration": "production"
    }
  }
}

Run the build:

nx build myapp
nx build myapp --configuration=production

server

Serve a Next.js application in development mode. Runs next dev under the hood with Nx’s watch integration.

{
  "targets": {
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "myapp:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "myapp:build:development",
          "dev": true
        },
        "production": {
          "buildTarget": "myapp:build:production",
          "dev": false
        }
      }
    }
  }
}

Run the dev server:

nx serve myapp

Inferred tasks

When @nx/next/plugin is registered in nx.json, Nx automatically infers targets from your next.config.js or next.config.ts file. This means you do not need to configure targets in project.json manually.

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

With inferred tasks configured, these commands work automatically:

nx build myapp    # next build
nx dev myapp      # next dev
nx start myapp    # next start (production server)

Configuration examples

next.config.ts with Nx paths

import { NextConfig } from 'next';
import { composePlugins, withNx } from '@nx/next';

const nextConfig: NextConfig = {
  nx: {
    svgr: false,
  },
};

const plugins = [withNx];

export default composePlugins(...plugins)(nextConfig);

Full project.json example

{
  "name": "myapp",
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "root": "myapp",
        "outputPath": "dist/myapp"
      },
      "configurations": {
        "development": {
          "debug": true
        },
        "production": {
          "debug": false
        }
      }
    },
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "myapp:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "myapp:build:development",
          "dev": true
        },
        "production": {
          "buildTarget": "myapp:build:production",
          "dev": false
        }
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint"
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "myapp/jest.config.ts"
      }
    }
  }
}

Importing workspace libraries

Next.js applications in an Nx workspace can import shared libraries using TypeScript path aliases. Nx configures these automatically via tsconfig.base.json.

// myapp/src/app/page.tsx
import { Button } from '@myorg/ui-components';
import { fetchData } from '@myorg/data-access';

Run nx graph to visualize the dependency graph between your Next.js applications and shared libraries.