Next.js Plugin for Nx

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.

Setting Up @nx/next

Add to an Existing Nx Workspace

nx add @nx/next

Verify the plugin is setup:

Check for @nx/next listed as a plugin:
Terminal window
```
nx report
```
Ensure inferred project targets are working:
Terminal window
```
nx show projects --with-target=build
```
Inspect a specific project configuration:
Terminal window
```
nx show project my-next-app
```

Create a New Workspace

npx create-nx-workspace@latest --preset=next

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:

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

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:

{
  "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:

{
  "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.

CI Considerations

See Set Up CI for a complete CI configuration guide.

Build and Test Only What Changed

nx affected -t build test lint

This uses the project graph to determine which projects are affected by your changes and only runs tasks for those. Read more about the benefits of nx affected.

Remote Caching

Share build cache results across your team and CI with remote caching:

nx connect

Static HTML Export for E2E Testing

Next.js applications support static HTML export by setting output: 'export' in next.config.js. The serve-static target serves these static files for E2E testing in CI, without requiring a Next.js server.

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.

React Monorepo Tutorial Build a React 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.