Configuration

Config file

You can customize your Nitro builder with a configuration file.

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  // Nitro options
})

import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'

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

Environment-specific config

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

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  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 { defineNitroConfig } from "nitro/config";

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

Config from package.json

You can also provide Nitro configuration under the nitro key in your package.json file.

Directory options

Nitro provides several options for controlling directory structure:

import { defineNitroConfig } from "nitro/config";

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

Environment variables

Certain Nitro behaviors can be configured using environment variables:

Runtime configuration

Nitro provides a runtime config API to expose configuration within your application, with the ability to update it at runtime by setting environment variables. This is useful when you want to expose different configuration values for different environments (e.g. development, staging, production). For example, you can use this to expose different API endpoints for different environments or to expose different feature flags.

First, you need to define the runtime config in your configuration file.

import { defineNitroConfig } from "nitro/config";

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

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

import { defineHandler } from "nitro/h3";
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 { defineNitroConfig } from "nitro/config";

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

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

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"

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

Do not forget that you can still universally access environment variables using import.meta.env or process.env but avoid using them in ambient global contexts to prevent unexpected behavior.

Production

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

NITRO_API_TOKEN="123"

In runtime config, define key using camelCase. In environment variables, define key using snake_case and uppercase.

{
  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 { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  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 { defineNitroConfig } from "nitro/config";

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

APP_DOMAIN="example.com"

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