Nx with Nuxt

Nuxt is a full stack web framework built on Vue. In a Nuxt monorepo, Nx caches task results and runs only the tasks a change affects.

The @nx/nuxt plugin adds generators, task inference, and caching to your Nuxt projects.

Requirements

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

Package	Supported Versions
`nuxt`	^3.0.0 \|\| ^4.0.0

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

Setting up a new Nx workspace with @nx/nuxt

You can create a new workspace that uses Nuxt with one of the following commands:

Generate a new monorepo with a Nuxt app

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

Installation

In any Nx workspace, you can install @nx/nuxt by running the following command:

nx add @nx/nuxt

This will install the correct version of @nx/nuxt.

How @nx/nuxt infers tasks

The @nx/nuxt plugin will create a task for any project that has an Nuxt configuration file present. Any of the following files will be recognized as an Nuxt configuration file:

nuxt.config.js
nuxt.config.ts
nuxt.config.mjs
nuxt.config.mts
nuxt.config.cjs
nuxt.config.cts

The configuration directory must also contain a package.json or project.json.

View inferred tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/nuxt configuration

The @nx/nuxt/plugin is configured in the plugins array in nx.json.

{
  "plugins": [
    {
      "plugin": "@nx/nuxt/plugin",
      "options": {
        "buildTargetName": "build",
        "serveTargetName": "serve",
        "buildStaticTargetName": "build-static",
        "serveStaticTargetName": "serve-static",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}

Option	Type	Default	Inferred behavior
`buildTargetName`	string	`build`	Runs and caches `nuxt build`, including `.nuxt` and `.output`.
`serveTargetName`	string	`serve`	Runs `nuxt dev` continuously.
`buildStaticTargetName`	string	`build-static`	Runs and caches `nuxt build --prerender`.
`serveStaticTargetName`	string	`serve-static`	Serves `dist` continuously after the static build task.
`buildDepsTargetName`	string	none	Name of an optional dependency build task.
`watchDepsTargetName`	string	none	Name of an optional dependency watch task.

Use include and exclude glob patterns on the plugin entry to scope inference. A target defaults plugin filter must use the exact identifier @nx/nuxt/plugin.

Wait for the dev server to be ready

The serve task reports to Nx that it's ready, with the address it listens on, when the Nuxt config loads the @nx/nuxt/ready-signal module. nuxt dev answers 503 until it has built the app and serves it, and the module reports once that stops. Generated apps include the module. In an existing app, add it to modules:

export default defineNuxtConfig({
  modules: ['@nx/nuxt/ready-signal'],
});

Without the module, the serve task gets a check that runs when the task runs, with the task's environment and options. It waits until the server answers with any status other than 503, at the address nuxt dev uses. The check reads that address in the order of the installed nuxi or @nuxt/cli package. From version 3.7.2, that order is:

The port comes from the --port or -p flag, then the first set of NUXT_PORT, NITRO_PORT, and PORT, then devServer.port in the Nuxt config, 3000 by default.
The host comes from the --host or -h flag, then the first set of NUXT_HOST, NITRO_HOST, and HOST, then devServer.host.

Version 3.30 reads only the flags and devServer. From 3.31, a variable set only in .env doesn't count. Versions before 3.7.2 read fewer of these sources, some in another order.

If another process holds that port and nuxt dev moves to a free one, this check can pass before the server is up. The module reports the address the server listens on, so it doesn't have this gap.

The serve-static task's file server reports its address once it listens. A task waits for either one only when its dependsOn entry sets waitFor to ready. A readyWhen on the target in targetDefaults or in the project configuration replaces the inferred check, and null turns it off. For the details, see wait for a continuous task to be ready.

Using Nuxt

Generate a new Nuxt app

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

Deploy a Nuxt app

Once you are ready to deploy your Nuxt application, you have absolute freedom to choose any hosting provider that fits your needs.

We have detailed how to deploy your Nuxt application to Vercel in a separate guide.

E2E testing

By default nuxt does not generate static HTML files when you run the build command. However, Nx provides a build-static target that you can use to generate static HTML files for your Nuxt application. Essentially, this target runs the nuxt build --prerender command to generate static HTML files.

To perform end-to-end (E2E) testing on static HTML files using a test runner like Cypress. When you create a Nuxt application, Nx automatically creates a serve-static target. This target is designed to serve the static HTML files produced by the build-static command.

This feature is particularly useful for testing in continuous integration (CI) pipelines, where resources may be constrained. Unlike the serve target, serve-static does not require a Nuxt's Nitro server to operate, making it more efficient and faster by eliminating background processes, such as file change monitoring.

To use the serve-static target for testing, run the following command:

nx serve-static my-nuxt-app

This command performs two actions:

It builds the Nuxt application and generates the static HTML files.
It serves the static HTML files with a file server.

It doesn't run tests. The generated E2E project uses serve-static as its web server, in CI for Cypress and in every Playwright run.

Set up CI for your Nuxt 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.