/nitro

Configuration & Runtime Config

Nitro is configured via nitro.config.ts (loaded with c12) or, when building with Vite, via the nitro key in vite.config.ts.

Config file

import { defineConfig } from "nitro";

export default defineConfig({
  // Nitro options
});

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [nitro()],
  nitro: {
    // Nitro options
  },
});

v3 renamed the package nitropack → nitro and defineNitroConfig → defineConfig.

Environment overrides & extending

export default defineConfig({
  logLevel: 3,
  $development: { debug: true },   // only during `nitro dev`
  $production: { minify: true },   // only during `nitro build`
  extends: "./base.config",        // inherit from another config/preset
});

Config can also live under a nitro key in package.json or in a .nitrorc file.

Key options

Directory defaults

Runtime config

Define defaults in config; override at runtime with NITRO_-prefixed env vars. Only keys declared in runtimeConfig can be overridden — env vars cannot introduce new keys.

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    apiToken: "dev_token",
    database: { host: "localhost", port: 5432 },
  },
});

Access it (note the dedicated subpath import):

import { defineHandler } from "nitro";
import { useRuntimeConfig } from "nitro/runtime-config";

export default defineHandler((event) => {
  return useRuntimeConfig().apiToken;
});

Env var mapping uses NITRO_ + UPPER_SNAKE_CASE, nested keys joined by _:

NITRO_API_TOKEN="123"
NITRO_DATABASE_HOST="db.example.com"
NITRO_DATABASE_PORT="5433"

• .env / .env.local are loaded only in nitro dev; in production use the platform's env vars.
• Values must be serializable; undefined/null fall back to "".
• Add a secondary prefix via runtimeConfig.nitro.envPrefix: "APP_" (checked alongside NITRO_).
• Enable experimental.envExpansion to expand {{VAR}} references inside runtime config strings.

Environment variables (built-in)

Key Points

• defineConfig from nitro is the v3 entry point; with Vite, options go under the nitro key.
• Use useRuntimeConfig() from nitro/runtime-config for env-overridable values; never read process.env in module top-level (edge runtimes only expose env during requests).
• experimental.* flags gate tasks, database, and openAPI.
• Types are imported from nitro/types (e.g. NitroRuntimeConfig), not nitro.