@nx/next - Executors

The @nx/next plugin provides various executors to help you create and configure next projects within your Nx workspace. Below is a complete reference for all available executors and their options.

build

Build a Next.js app.

project.json:

//...
{
  "name": "acme",
  "$schema": "node_modules/nx/schemas/project-schema.json",
  "sourceRoot": ".",
  "projectType": "application",
  "targets": {
    //...
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      }
    }
    //...
  }
}

nx run acme:build

Examples

For Next.js Standalone projects

{% tabs %} {% tab label=“Default configuration” %}

This is the default configuration for Next.js standalone projects. Our @nx/next:build executor is integrated to use Next.js’ CLI. You can read more about the build options at Next.js CLI Options

    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": "."
        },
        "production": {}
      }
    },

{% /tab %} {% tab label=“Enable debug” %}

You can create a debug build for more verbose output by:

Using the --debug flag

nx run acme:build:development --debug

Updating the build options to include debug.

    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
          "debug": true
        },
        "production": {}
      }
    },

nx run acme:build:development

{% /tab %}

{% tab label=“Adding profiling” %}

You can enable profiing for React by

Using the --profile flag

nx run acme:build:production --profile

Updating the build options to include profile.

    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
        },
        "production": {
          "profile": true
        }
      }
    },

nx run acme:build:production

{% /tab %}

{% tab label=“Enable experimental app only” %}

Since Next.js 13 the app/ directory it is reserved. You can enable to build only app/ routes by

Using the --experimentalAppOnly flag

nx run acme:build:production --experimentalAppOnly

Updating the build options to include experimentalAppOnly.

    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
          "experimentalAppOnly": true
        },
        "production": {}
      }
    },

nx run acme:build:production

{% /tab %}

{% /tabs %}

Options

Option	Type	Description	Default
outputPath	string [required]	The output path of the generated files.
buildLibsFromSource	boolean	Read buildable libraries from source instead of building them separately.	true
debug	boolean	Enable Next.js debug build logging
experimentalAppOnly	boolean	Only build ‘app’ routes
experimentalBuildMode	string	Change the build mode.
fileReplacements	array	Replace files with other files in the build.	[]
generateLockfile	boolean	Generate a lockfile (e.g. package-lock.json) that matches the workspace lockfile to ensure package versions match.	false
includeDevDependenciesInPackageJson	boolean	Include devDependencies in the generated package.json file. By default only production dependencies are included.	false
nextConfig	string	Path (relative to workspace root) to a function which takes phase, config, and builder options, and returns the resulting config. This is an advanced option and should not be used with a normal Next.js config file (i.e. next.config.js).
profile	boolean	Used to enable React Production Profiling
skipOverrides	boolean	Do not add a overrides and resolutions entries to the generated package.json file. Only works in conjunction with generatePackageJson option.
skipPackageManager	boolean	Do not add a packageManager entry to the generated package.json file.

server

Serve a Next.js app.

project.json:

//...
{
  "name": "acme",
  "$schema": "node_modules/nx/schemas/project-schema.json",
  "sourceRoot": ".",
  "projectType": "application",
  "targets": {
    //...
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "production",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      }
    }
    //...
  }
}

nx run acme:serve

Examples

For Next.js Standalone projects

{% tabs %} {% tab label=“Default configuration” %}

This is the default configuration for Next.js standalone projects. Our @nx/next:server executor is integrated to use Next.js’ CLI. You can read more about the serve options at Next.js CLI Options

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

{% /tab %} {% tab label=“Enable turbo” %}

Turbopack (beta) is a cutting-edge bundler designed for JavaScript and TypeScript. To read more about support features see Next.js Turbopack Documentation

In the context of Nx, you can utilize Turbopack within both the pages and app directories of Next.js to enhance local development speed. To activate Turbopack, simply:

Append the --turbo flag while executing the Nx development server.

nx run acme:serve --turbo

Updating the build options to include turbo.

    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true,
          "turbo": true
        },
        //
    }
  }

nx run acme:serve

{% /tab %}

{% tab label=“Adding keep alive timeout” %}

When using Nx with Next.js behind a downstream proxy, it’s important to make sure that the keep-alive timeouts of Next.js’ HTTP server are set to longer durations than the timeouts of the proxy. If you don’t do this, Node.js will unexpectedly end TCP connections without notifying the proxy when the keep-alive timeout is reached. This can lead to a proxy error when the proxy tries to reuse a connection that Node.js has already terminated.

To configure timeout values (in milliseconds) you can:

Pass --keepAliveTimeout

nx run acme:serve --keepAliveTimeout 60000

Updating the serve options to include keepAliveTimeout.

    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true,
          "keepAliveTimeout": 60000
        },
        //
    }
  }

nx run acme:serve

{% /tab %}

{% /tabs %}

Options

Option	Type	Description	Default
buildTarget	string [required]	Target which builds the application.
buildLibsFromSource	boolean	Read buildable libraries from source instead of building them separately.	true
customServerHttps:	boolean	Enable HTTPS support for the custom server.
customServerTarget	string	Target which builds the custom server.
dev	boolean	Serve the application in the dev mode.	true
experimentalHttps	boolean	Enable HTTPS support for the Next.js development server.
experimentalHttpsCa	string	Path to a HTTPS certificate authority file.
experimentalHttpsCert	string	Path to a HTTPS certificate file.
experimentalHttpsKey	string	Path to a HTTPS key file.
hostname	string	Hostname on which the application is served.
keepAliveTimeout	number	Max milliseconds to wait before closing inactive connection.
port	number	Port to listen on.	4200
quiet	boolean	Hide error messages containing server information.	false
staticMarkup	boolean	Static markup.	false
turbo	boolean	Activate the incremental bundler for Next.js, which is implemented in Rust. Please note, this feature is exclusively available in development mode.