Configuration
- Config Reference

Configuration

In order to customize nitro’s behavior, we create a file named nitro.config.ts.

// nitro.config.ts
import { defineNitroConfig } from 'nitropack'
export default defineNitroConfig({
})

Config Reference

`preset`

Use preset option NITRO_PRESET environment variable for custom production preset.

Preset for development mode is always nitro-dev and default node-server for production building a standalone Node.js server.

The preset will automatically be detected when the preset option is not set and running in known environments.

`logLevel`

Default: 3 (1 when the testing environment is detected)

Log verbosity level. See unjs/consola#level for more information.

`runtimeConfig`

Default: { nitro: { ... }, ...yourOptions }

Server runtime configuration.

Note:: nitro namespace is reserved.

`experimental`

Default: {}

Enable experimental features. Currently, non are available!

`storage`

Default: {}

Storage configuration.

`timing`

Default: false

Enable timing information.

`renderer`

Path to main render (file should export an event handler as default)

`serveStatic`

Default: false

Serve public/ assets in production.

Note: It is highly recommended that your edge CDN (nginx, apache, cloud) serves the public/ directory instead.

`publicAssets`

Public asset directories to serve in development and bundle in production.

If a public/ directory is detected, it will be added by default, but you can add more by yourself too!

`serverAssets`

Assets can be accessed in server logic and bundled in production.

`devServer`

Default: { watch: [] }

Dev server options. You can use watch to make the dev server reload if any file changes in specified paths.

`watchOptions`

Watch options for development mode. See chokidar for more information.

`autoImport`

Auto import options. See unjs/unimport for more information.

`plugins`

Default: []

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

`virtual`

Default: {}

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

`baseURL`

Default: / (or NITRO_APP_BASE_URL environment variable if provided)

Server’s main base URL.

`handlers`

Server handlers and routes.

If routes/, api/ or middleware/ directories exist, they will be automatically added to the handlers array.

`devHandlers`

Regular handlers refer to the path of handlers to be imported and transformed by rollup.

There are situations in that we directly want to provide a handler instance with programmatic usage.

We can use devHandlers but note that they are only available in development mode and not in production build.

`errorHandler`

Path to a custom runtime error handler. Replacing nitro’s built-in error page.

Example:

import { defineNitroConfig } from 'nitropack'
export default defineNitroConfig({
  errorHandler: '~/error'
})

import type { NitroErrorHandler } from 'nitropack'
export default <NitroErrorHandler> function (error, event) {
  event.res.end('[custom error handler] ' + error.stack)
}

`routes`

🧪 Experimental!

Route options. It is a map from route pattern (following unjs/radix3) to options.

Example:

{
  routes: {
    '/blog/**': { swr: true }
  }
}

`prerenderer`

Default: { crawlLinks: false, routes: [] }

Prerendered options. Any route specified will be fetched during the build and copied to the .output/public directory as a static asset.

If crawlLinks option is set to true, nitro starts with / by default (or all routes in routes array) and for HTML pages extracts <a href=""> tags and prerender them as well.

`rootDir`

Project main directory

`srcDir`

Project source directory. Same as rootDir unless specified. Helpful to move code into src/.

`scanDirs`

Default: (source directory when empty array)

List of directories to scan and auto-register files, such as API routes.

`buildDir`

Default: .nitro

nitro’s temporary working directory for generating build-related files.

`output`

Default: { dir: '.output', serverDir: '.output/server', publicDir: '.output/public' }

Output directories for production bundle.