Features

import { defineConfig } from "nitro";

#features

• Default: {}

Enable built-in features.

#runtimeHooks

• Default: auto-detected (enabled if there is at least one nitro plugin)

Enable runtime hooks for request and response.

#websocket

• Default: false

Enable WebSocket support.

#fastResponse

• Default: true when node is enabled, otherwise false

Replace the global Response with srvx FastResponse, so new Response() in your handlers skips the native Response overhead in Node.js. instanceof Response keeps working for both native and fast responses.

Has no effect in runtimes without a FastResponse implementation (Bun, Deno, workers).

export default defineConfig({
  features: {
    runtimeHooks: true,
    websocket: true, // enable WebSocket support
    fastResponse: false, // use the native global Response
  },
});

#experimental

• Default: {}

Enable experimental features.

#openAPI

• Default: false

Enable /_scalar, /_swagger and /_openapi.json endpoints.

#typescriptBundlerResolution

Enable TypeScript bundler module resolution. See TypeScript#51669.

#asyncContext

Enable native async context support for useRequest().

#sourcemapMinify

Set to false to disable experimental sourcemap minification (enabled by default when sourcemap is enabled).

#envExpansion

Allow env expansion in runtime config. See the configuration guide and #2043.

#database

Enable experimental database support. See Database.

#tasks

Enable experimental tasks support. See Tasks.

#tracingLogger

Log Nitro tracing-channel spans to the console using a built-in, dependency-free telemetry sink that logs each completed span (h3, srvx, unstorage, db0, ...). Requires tracingChannel to be enabled.

export default defineConfig({
  experimental: {
    typescriptBundlerResolution: true,
    asyncContext: true,
    envExpansion: true,
    database: true,
    tasks: true,
  },
});

#openAPI

Top-level OpenAPI configuration.

You can pass an object to modify your OpenAPI specification:

openAPI: {
  meta: {
    title: 'My Awesome Project',
    description: 'This might become the next big thing.',
    version: '1.0'
  }
}

These routes are disabled by default in production. To enable them, use the production key. "runtime" allows middleware usage, and "prerender" is the most efficient because the JSON response is constant.

openAPI: {
    // IMPORTANT: make sure to protect OpenAPI routes if necessary!
    production: "runtime", // or "prerender"
}

To customize the Scalar integration, pass a configuration object like this:

openAPI: {
  ui: {
    scalar: {
      theme: 'purple'
    }
  }
}

To customize the Swagger UI, pass any Swagger UI configuration option:

openAPI: {
  ui: {
    swagger: {
      persistAuthorization: true,
      deepLinking: true,
      docExpansion: 'none',
      filter: true,
    }
  }
}

To customize the endpoints:

openAPI: {
  route: "/_docs/openapi.json",
  ui: {
    scalar: {
      route: "/_docs/scalar"
    },
    swagger: {
      route: "/_docs/swagger"
    }
  }
}

#renderer

• Type: false | { handler?: string, static?: boolean, template?: string }

Points to main render entry (file should export an event handler as default).

export default defineConfig({
  renderer: {
    handler: "~/renderer", // path to the render handler
  },
});

#ssrRoutes

Routes that should be server-side rendered.

export default defineConfig({
  ssrRoutes: ["/app/**"],
});

#modules

• Default: []

An array of Nitro modules. Modules can be a string (path), a module object with a setup function, or a function.

export default defineConfig({
  modules: [
    "./modules/my-module.ts",
    (nitro) => {
      nitro.hooks.hook("compiled", () => { /* ... */ });
    },
  ],
});

#plugins

• Default: []

An array of paths to nitro plugins. They will be executed in order on the first initialization.

Note that Nitro auto-registers the plugins in the plugins/ directory.

export default defineConfig({
  plugins: [
    "~/plugins/my-plugin.ts",
  ],
});

#tasks

• Default: {}

Task definitions. Each key is a task name with an optional handler path and description.

Tasks scanned from <serverDir>/tasks/ only need a description here. A handler is imported as-is and is not resolved against the project root, so it has to be an absolute path or a package name.

import { fileURLToPath } from "node:url";

export default defineConfig({
  tasks: {
    "db:migrate": {
      description: "Run database migrations",
    },
    "db:seed": {
      handler: fileURLToPath(new URL("scripts/seed.ts", import.meta.url)),
      description: "Seed the database",
    },
  },
});

#scheduledTasks

• Default: {}

Map of cron expressions to task name(s).

export default defineConfig({
  scheduledTasks: {
    "0 * * * *": "cleanup:temp",
    "*/5 * * * *": ["health:check", "metrics:collect"],
  },
});

#virtual

• Default: {}

A map from dynamic virtual import names to their contents or an (async) function that returns it.

export default defineConfig({
  virtual: {
    "#config": `export default { version: "1.0.0" }`,
  },
});

#wasm

• Type: false | UnwasmPluginOptions
• Default: {}

WASM support configuration. See unwasm for options.

export default defineConfig({
  wasm: {}, // enable WASM import support
});