Configuration

#Config file

You can customize Nitro with a configuration file. Depending on your setup, define options in nitro.config.ts, or under the nitro key in vite.config.ts when using the Vite plugin.

import { defineConfig } from "nitro";

export default defineConfig({
  // Nitro options
})

#Supported configuration files

Nitro loads its configuration using c12 from the project root directory (the directory passed to the nitro CLI, defaulting to the current working directory). The following locations are checked in order and the first matching file is used:

• nitro.config.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}
• .config/nitro.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}
• .config/nitro.config.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}

Using nitro.config.ts is the recommended convention.

An extensionless .nitrorc file in the same directory is also loaded (using key=value syntax) and merged with lower priority than the main configuration file.

When using the Vite plugin, options can also be passed inline with the nitro key in vite.config.ts (as shown above).

#Environment-specific config

Using c12 conventions, you can provide environment-specific overrides using $development and $production keys:

import { defineConfig } from "nitro";

export default defineConfig({
  logLevel: 3,
  $development: {
    // Options applied only in development mode
    debug: true,
  },
  $production: {
    // Options applied only in production builds
    minify: true,
  },
})

The environment name is "development" during nitro dev and "production" during nitro build.

#Extending configs

You can extend from other configs or presets using the extends key:

import { defineConfig } from "nitro";

export default defineConfig({
  extends: "./base.config",
})

#Directory options

Nitro provides several options for controlling directory structure:

import { defineConfig } from "nitro";

export default defineConfig({
  serverDir: "server",
  buildDir: "node_modules/.nitro",
  output: {
    dir: ".output",
  },
})

#Environment variables

Certain Nitro behaviors can be configured using environment variables. These variables configure Nitro itself at build and startup time. To expose your own values to the application, use runtime configuration instead.

#Runtime configuration

Runtime config lets you expose configuration values to your application and override them at runtime using environment variables. This is useful for values that differ between environments (development, staging, production), such as API endpoints or feature flags.

First, define the runtime config in your configuration file.

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    apiToken: "dev_token", // `dev_token` is the default value
  }
});

You can now access the runtime config using useRuntimeConfig().

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

export default defineHandler((event) => {
  return useRuntimeConfig().apiToken; // Returns `dev_token`
});

#Nested objects

Runtime config supports nested objects. Keys at any depth are mapped to environment variables using the NITRO_ prefix and UPPER_SNAKE_CASE conversion:

import { defineConfig } from "nitro";

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

#Serialization

Runtime config values must be serializable (strings, numbers, booleans, plain objects, and arrays). Non-serializable values (class instances, functions, etc.) will trigger a warning at build time.

Values that are undefined or null in the config are replaced with empty strings ("") as a fallback.

#Local development

You can update the runtime config using environment variables. You can use a .env or .env.local file in development and use platform variables in production (see below).

Create an .env file in your project root:

NITRO_API_TOKEN="123"

Restart the development server, fetch the /api/example endpoint, and you should see 123 as the response instead of dev_token.

You can still access environment variables directly using import.meta.env or process.env, but avoid reading them in ambient global contexts (at the top level of modules) to prevent unexpected behavior.

#Production

You can define variables in your production environment to update the runtime config.

NITRO_API_TOKEN="123"

Keys are camelCase in runtime config and UPPER_SNAKE_CASE in environment variables.

{
  helloWorld: "foo"
}

NITRO_HELLO_WORLD="foo"

#Custom env prefix

You can configure a secondary environment variable prefix using the nitro.envPrefix runtime config key. This prefix is checked in addition to the default NITRO_ prefix:

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    nitro: {
      envPrefix: "APP_",
    },
    apiToken: "",
  },
});

With this configuration, both NITRO_API_TOKEN and APP_API_TOKEN will be checked as overrides.

#Env expansion

When enabled, environment variable references using {{VAR_NAME}} syntax in runtime config string values are expanded at runtime:

import { defineConfig } from "nitro";

export default defineConfig({
  experimental: {
    envExpansion: true,
  },
  runtimeConfig: {
    url: "https://{{APP_DOMAIN}}/api",
  },
});

APP_DOMAIN="example.com"

At runtime, useRuntimeConfig().url will resolve to "https://example.com/api".