CLI

When nitro is installed as a project dependency, run it through your package manager (npx nitro, pnpm nitro, yarn nitro, bun nitro, ...) or add it to your package.json scripts:

{
  "scripts": {
    "dev": "nitro dev",
    "build": "nitro build",
    "preview": "nitro preview"
  }
}

Then use npm run dev, pnpm dev, etc. as shown in the quick start guide.

All commands except nitro create accept a project root directory, either as a positional argument (nitro build ./my-app) or with the --dir flag (preferred). It defaults to the current directory. nitro fetch only accepts --dir, as its positional argument is the URL.

#nitro create

Create a new Nitro project from a template. Nitro ships the templates itself, so no download is needed, and the nitro dependency of the new project is set to the version that created it.

npx nitro create [dir] [--template <template>] [--packageManager <name>] [--no-install] [--gitInit] [--force]

When run in an interactive terminal, nitro create prompts for anything not set by a flag. Otherwise it creates the vite template in nitro-app/, installs dependencies with the package manager that ran it (or npm), and fails if the directory is not empty.

Unknown options, options without a value and extra arguments are rejected. When run by an AI agent without a directory or template, it prints the available options and exits, so the agent can choose them explicitly. Once done, it prints a summary of what was created (directory, template, package manager, dependencies and git) followed by the next steps, including when installing dependencies fails.

Example:

npx nitro create my-api --template rolldown --packageManager pnpm

#nitro dev

Start the development server with hot reloading.

npx nitro dev [--dir <dir>] [--port <port>] [--host <host>] [--envName <name>]

The dev server watches your Nitro config: changes to runtimeConfig or routeRules are hot reloaded, while other config changes trigger a full dev server restart.

An HTML error page (5xx) opened in the browser reloads by itself once the server reloads after a fix, also with the Vite plugin. It waits on the /_nitro/dev/reload route (under baseURL), which is reserved in development.

Example:

npx nitro dev --port 4000 --host 0.0.0.0

#nitro build

Build the project for production. Nitro prepares the build directory, copies public assets, prerenders any configured routes, and bundles the server into the output directory (.output/ by default).

npx nitro build [--dir <dir>] [--preset <preset>] [--minify] [--builder <builder>] [--compatibility-date <date>] [--envName <name>]

Example:

npx nitro build --preset cloudflare_module

#NITRO_PRESET vs --preset

Both set the deployment preset, and the --preset flag takes precedence over the NITRO_PRESET environment variable. The environment variable is handy on deployment platforms and in CI, where you often cannot change the build command:

NITRO_PRESET=cloudflare_module npm run build

#nitro preview

Start a local server to preview the production build output.

npx nitro preview [--dir <dir>] [--port <port>] [--host <host>]

Example:

npx nitro build
npx nitro preview

#nitro serve

Start the server from the project sources, without a build step (alias: nitro start).

npx nitro serve [--dir <dir>] [--port <port>] [--host <host>] [--dev] [--envName <name>]

The server runs in production mode without a builder (builder: false), whatever builder is configured: your files run directly in the server process, and public assets are served from their source directories. With buildPlugins, whose hooks may be async, they run in a Node.js worker that listens on the port itself instead. WebSocket handlers and scheduled tasks are supported. Environment variables are loaded from .env.production and .env files, without overriding existing ones.

On SIGINT or SIGTERM, the server stops accepting connections, waits for in-flight requests and runs the close hooks before exiting. If the server (or its worker) exits unexpectedly, the command exits with code 1 so a process manager can restart it.

Example:

npx nitro start --port 8080

#nitro fetch

Send one request to the server from the project sources, without a build step, print the response and exit (alias: nitro curl).

npx nitro fetch [url] [--dir <dir>] [--no-dev] [--envName <name>] [curl options]

The URL can be a path (/api/hello, resolved against http://localhost) or a full URL starting with http:// or https://. It defaults to /. Its host is sent as the host header (unless set with -H), so the server sees it. The project root directory is only set with --dir, as the positional argument is the URL.

When nitro dev (or vite dev with the Vite plugin) is running for the project, the request is sent to that dev server, so you get the current code with its dev behavior (public assets, devProxy, ...), and its logs stay in its terminal. Otherwise, a server starts like with nitro serve (in production mode, with .env.production and .env files) and closes after the response, running the close hooks. Use --no-dev to always start a server. With --envName, the dev server is only used if it runs with the same environment name (development, unless set with nitro dev --envName). Vite only accepts the hosts of its server.allowedHosts option (and localhost).

The response body is streamed to stdout as it arrives, while the logs go to stderr, so the output can be piped (nitro fetch /api/users | jq).

A subset of the curl options is supported:

Redirects are not followed. With a 4xx or 5xx response status, the body is printed and the command exits with code 22 (like curl --fail-with-body). If the output can not be written, for example when stdout is closed early (nitro fetch | head), it stops and exits with code 23. On SIGINT or SIGTERM, it stops and exits with code 130 or 143. Other errors exit with code 1, and invalid arguments with code 2. The server is always closed before exiting, running the close hooks.

Example:

npx nitro fetch /api/hello
npx nitro curl -i -X POST /api/users --json '{"name":"nitro"}'

#nitro deploy

Build the project, then run the deploy command of the selected preset.

npx nitro deploy [--dir <dir>] [--prebuilt] [build flags...] [-- <extra deploy args>]

All nitro build flags (--preset, --minify, --builder, --compatibility-date, --envName, ...) are also accepted and applied to the build step. Any arguments after -- are appended to the underlying deploy command (or passed as args to a function deploy command).

Example:

# Build with the cloudflare_module preset, then run wrangler deploy
npx nitro deploy --preset cloudflare_module

# Deploy an existing build without rebuilding
npx nitro deploy --prebuilt

#nitro task

Operate on Nitro tasks (experimental).

#nitro task list

List available tasks with their descriptions.

npx nitro task list [--dir <dir>]

#nitro task run

Run a task by name, optionally with a JSON payload.

npx nitro task run <name> [--dir <dir>] [--payload <json>]

Example:

npx nitro task run db:migrate --payload '{"force": true}'

#nitro docs

Open the Nitro documentation (nitro.build) in your browser, optionally at a specific page path (e.g. /docs/routing).

npx nitro docs [page]