Config
General
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 for more information.
runtimeConfig
- Default:
{ nitro: { ... }, ...yourOptions }
Server runtime configuration.
Note:: nitro
namespace is reserved.
Features
experimental
- Default:
{}
Enable experimental features.
openAPI
Enable /_scalar
, /_swagger
and /_openapi.json
endpoints.
- Default:
false
You can pass an object on the root level to modify your OpenAPI specification:
openAPI: {
meta: {
title: 'My Awesome Project',
description: 'This might become the next big thing.',
version: '1.0'
}
}
If you like to customize the Scalar integration, you can pass a configuration object like this:
openAPI: {
ui: {
scalar: {
theme: 'purple'
}
}
}
Or if you want to customize the endpoints:
openAPI: {
route: "/_docs/openapi.json",
ui: {
scalar: {
route: "/_docs/scalar"
},
swagger: {
route: "/_docs/swagger"
}
}
}
wasm
Enable WASM support
legacyExternals
When enabled, legacy (unstable) experimental rollup externals algorithm will be used.
future
- Default:
{}
New features pending for a major version to avoid breaking changes.
nativeSWR
Uses built-in SWR functionality (using caching layer and storage) for Netlify and Vercel presets instead of falling back to ISR behavior.
storage
- Default:
{}
Storage configuration, read more in the Storage Layer section.
timing
- Default:
false
Enable timing information:
- Nitro startup time log
Server-Timing
header on HTTP responses
renderer
Path to main render (file should export an event handler as default)
serveStatic
- Type:
boolean
|'node'
|'deno'
- Default: depends of the deployment preset used.
Serve public/
assets in production.
Note: It is highly recommended that your edge CDN (Nginx, Apache, Cloud) serves the .output/public/
directory instead of enabling compression and higher lever caching.
noPublicDir
- Default:
false
If enabled, disabled .output/public
directory creation. Skipping to copy public/
dir and also disables pre-rendering.
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!
It's possible to set Cache-Control headers for assets using the maxAge
option:
publicAssets: [
{
baseURL: "images",
dir: "public/images",
maxAge: 60 * 60 * 24 * 7, // 7 days
},
],
The config above generates the following header in the assets under public/images/
folder:
cache-control: public, max-age=604800, immutable
The dir
option is where your files live on your file system; the baseURL
option is the folder they will be accessible from when served/bundled.
compressPublicAssets
- Default:
{ gzip: false, brotli: false }
If enabled, Nitro will generate a pre-compressed (gzip and/or brotli) version of supported types of public assets and prerendered routes larger than 1024 bytes into the public directory. The best compression level is used. Using this option you can support zero overhead asset compression without using a CDN.
List of compressible MIME types:
application/dash+xml
application/eot
application/font
application/font-sfnt
application/javascript
application/json
application/opentype
application/otf
application/pdf
application/pkcs7-mime
application/protobuf
application/rss+xml
application/truetype
application/ttf
application/vnd.apple.mpegurl
application/vnd.mapbox-vector-tile
application/vnd.ms-fontobject
application/wasm
application/xhtml+xml
application/xml
application/x-font-opentype
application/x-font-truetype
application/x-font-ttf
application/x-httpd-cgi
application/x-javascript
application/x-mpegurl
application/x-opentype
application/x-otf
application/x-perl
application/x-ttf
font/eot
font/opentype
font/otf
font/ttf
image/svg+xml
text/css
text/csv
text/html
text/javascript
text/js
text/plain
text/richtext
text/tab-separated-values
text/xml
text/x-component
text/x-java-source
text/x-script
vnd.apple.mpegurl
serverAssets
Assets can be accessed in server logic and bundled in production. Read more.
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.
imports
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.
Note that Nitro auto-register the plugins in the plugins/
directory, learn more.
virtual
- Default:
{}
A map from dynamic virtual import names to their contents or an (async) function that returns it.
Routing
baseURL
Default: /
(or NITRO_APP_BASE_URL
environment variable if provided)
Server's main base URL.
apiBaseURL
- Default :
/api
Changes the default api base URL prefix.
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.
For example:
import { defineEventHandler } from 'h3'
export default defineNitroConfig({
devHandlers: [
{
route: '/',
handler: defineEventHandler((event) => {
console.log(event)
})
}
]
})
defineEventHandler
is a helper function from h3
library.devProxy
Proxy configuration for development server.
You can use this option to override development server routes and proxy-pass requests.
{
devProxy: {
'/proxy/test': 'http://localhost:3001',
'/proxy/example': { target: 'https://example.com', changeOrigin: true }
}
}
See unjs/httpxy for all available target options.
errorHandler
Path to a custom runtime error handler. Replacing nitro's built-in error page.
The error handler is given an H3Error
and H3Event
. If the handler returns a promise it is awaited.
The handler is expected to send a response of its own.
Below is an example where a plain-text response is returned using h3's functions.
Example:
export default defineNitroConfig({
errorHandler: "~/error",
});
routeRules
🧪 Experimental!
Route options. It is a map from route pattern (following unjs/radix3) to route options.
When cache
option is set, handlers matching pattern will be automatically wrapped with defineCachedEventHandler
.
See the Cache API for all available cache options.
swr: true|number
is shortcut for cache: { swr: true, maxAge: number }
Example:
routeRules: {
'/blog/**': { swr: true },
'/blog/**': { swr: 600 },
'/blog/**': { static: true },
'/blog/**': { cache: { /* cache options*/ } },
'/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
'/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
'/old-page': { redirect: '/new-page' }, // uses status code 307 (Temporary Redirect)
'/old-page2': { redirect: { to:'/new-page2', statusCode: 301 } },
'/old-page/**': { redirect: '/new-page/**' },
'/proxy/example': { proxy: 'https://example.com' },
'/proxy/**': { proxy: '/api/**' },
}
prerender
Default:
{
autoSubfolderIndex: true,
concurrency: 1,
interval: 0,
failOnError: false,
crawlLinks: false,
ignore: [],
routes: [],
retry: 3,
retryDelay: 500
}
Prerendered options. Any route specified will be fetched during the build and copied to the .output/public
directory as a static asset.
Any route (string) that starts with a prefix listed in ignore
or matches a regular expression or function will be ignored.
If crawlLinks
option is set to true
, nitro starts with /
by default (or all routes in routes
array) and for HTML pages extracts <a>
tags and prerender them as well.
You can set failOnError
option to true
to stop the CI when an error if Nitro could not prerender a route.
The interval
and concurrency
options lets you control the speed of pre-rendering, can be useful to avoid hitting some rate-limit if you call external APIs.
Set autoSubfolderIndex
lets you control how to generate the files in the .output/public
directory:
# autoSubfolderIndex: true (default)
/about -> .output/public/about/index.html
# autoSubfolderIndex: false
/about -> .output/public/about.html
This option is useful when your hosting provider does not give you an option regarding the trailing slash.
The prerenderer will attempt to render pages 3 times with a delay of 500ms. Use retry
and retryDelay
to change this behavior.
Directories
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.
apiDir
- Default :
api
Defines a different directory to scan for api route handlers.
routesDir
- Default :
routes
Defines a different directory to scan for route handlers.
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.
Advanced
dev
- Default:
true
for development andfalse
for production.
⚠️ Caution! This is an advanced configuration. things can go wrong if misconfigured.
typescript
Default: { generateTsConfig: true }
nodeModulesDirs
⚠️ Caution! This is an advanced configuration. things can go wrong if misconfigured.
Additional node_modules
to search when resolving a module. By default user directory is added.
hooks
⚠️ Caution! This is an advanced configuration. things can go wrong if misconfigured.
nitro hooks. See unjs/hookable for more information.
commands
⚠️ Caution! This is an advanced configuration. things can go wrong if misconfigured.
Preview and deploy command hints are usually filled by deployment presets.
devErrorHandler
⚠️ Caution! This is an advanced configuration. things can go wrong if misconfigured.
A custom error handler function for development errors.
Rollup
rollupConfig
Additional rollup configuration.
entry
Rollup entry.
unenv
Options for unjs/unenv preset.
alias
Rollup aliases options.
minify
- Default:
false
Minify bundle.
inlineDynamicImports
Avoid creating chunks.
sourceMap
Enable source map generation. See options
- Default:
true
node
Specify whether the build is used for Node.js or not. If set to false
, nitro tries to mock Node.js dependencies using unjs/unenv and adjust its behavior.
analyze
If enabled, will analyze server bundle after build using rollup-plugin-visualizer. You can also pass your custom options.
moduleSideEffects
Default: ['unenv/runtime/polyfill/', 'node-fetch-native/polyfill']
Rollup specific option. Specifies module imports that have side-effects
replace
Rollup specific option.
commonJS
Rollup specific option. Specifies additional configuration for the rollup CommonJS plugin.
Preset options
firebase
The options for the firebase functions preset. See Preset Docs
vercel
The options for the vercel preset. See Preset Docs
cloudflare
The options for the cloudflare preset. See Preset Docs