Build
Bundler selection and build output tuning.
Note
All examples on this page assume the following import in nitro.config.ts:
import { defineConfig } from "nitro";#builder
- Type:
"rollup"|"rolldown"|"rspack"|"vite"|"bun"|false - Default:
undefined(auto-detected)
Specify the bundler to use for building.
export default defineConfig({
builder: "vite",
});When not set, Nitro uses vite if your vite.config uses the nitro() plugin, otherwise rolldown. The builder package is resolved from your project (rolldown also through your vite) and installed on demand when building (except in CI, see deps.install). In development, if rolldown is not installed and no rollupConfig or rolldownConfig is set, nitro dev runs without a builder (builder: false) and nitro build offers to install it. When Nitro runs with Bun (for example bun --bun nitro build) and neither rolldown nor vite is installed in your project, the experimental bun builder is used instead, in development too.
Set builder: false (experimental) to run the server sources without bundling. nitro dev then runs your files directly in an env-runner worker, Nitro's virtual modules are served from memory, and a fresh worker starts on each change. nitro start (or nitro serve) runs the sources the same way in production mode, without a build step, whatever builder is configured. nitro preview only serves a build output. Prerendering runs the sources the same way, and is also used by the vite builder when rolldown is not installed. nitro build is not supported yet.
Modules are transformed on demand, like in a bundled build: TypeScript and JSX, import.meta.* and replace values, alias, extensionless imports, raw:/text/bytes imports and WebAssembly.
Note
- On Bun, aliases without a file extension (such as
~/utils) and WebAssembly imports are not resolved yet. - Files outside the project, its scan dirs and Nitro (such as linked workspace packages) are loaded as-is, without these transforms.
- Bundler options (
rollupConfig,rolldownConfig) and plugins added by modules with thebuild:confighook do not apply. UsebuildPluginsfor plugins.
Set builder: "rspack" (experimental) to bundle the server with Rspack (@rspack/core v2.3+, installed on demand). Nitro's own build plugins and buildPlugins run inside Rspack, and TypeScript and JSX are compiled with its built-in SWC loader. Use rspackConfig for additional options.
Note
With rspack, these options of rollupConfig and rolldownConfig (used by presets) are applied: plugins, external (called before resolving the import), output.entryFileNames and output.chunkFileNames (strings with [name] and [hash]), output.banner, output.footer, output.intro and output.outro (strings or synchronous functions), output.inlineDynamicImports: true, output.sourcemapExcludeSources and output.sourcemapPathTransform. Nitro warns about the other options, which are ignored.
Set builder: "bun" (experimental) to bundle the server with Bun's bundler (Bun.build). It requires running Nitro with Bun (for example bun --bun nitro build), and Nitro throws an error otherwise. It works with every preset, not only bun, and supports nitro dev.
Note
- Nitro's build plugins,
buildPluginsand the plugins ofrollupConfigandrolldownConfigrun in a single Bun plugin.buildStart,resolveId,load,transform,buildEnd,renderChunk,resolveFileUrl,generateBundleandwriteBundlehooks are supported. Files other than JavaScript and TypeScript reachtransformhooks only when aloadhook loads them or the hook'sfilternames them byid. Bun has no input source maps, sotransformandrenderChunkhooks do not update source maps. - From
rollupConfigandrolldownConfig, onlyplugins,external,platform: "node"and theoutputoptionsentryFileNames,chunkFileNames,format,inlineDynamicImports,bannerandfooter(as strings) apply. UsebunConfigfor other options. - Chunks are named by Bun (
_chunks/[name]-[hash].mjs) and library chunks are not grouped. - Bun has no
neutraltarget: presets without Node.js compatibility use thebrowsertarget, which resolves thebrowserexport condition andbrowserfield of packages first. - Bundled CommonJS modules get
__dirnameand__filenameas absolute paths of the build machine.
#buildPlugins
- Type:
NitroBuildPluginOption[] - Default:
[]
Build plugins applied with every builder (rollup, rolldown, rspack, vite, bun and false). Nested arrays and promises are resolved, falsy entries are skipped.
Plugins use the Rollup plugin interface. Prefer the resolveId, load and transform hooks with a filter: they are the ones supported by all builders.
Plugins with enforce: "pre" are placed before Nitro's own plugins, the others after them (enforce: "post" last). A hook's own order takes precedence: several Nitro hooks (such as virtual module resolution) use order: "pre", so use it too for a hook that must run before them.
Note
- Builders differ in what runs around the plugins.
transformhooks receive TypeScript and JSX untransformed withrolldownandbun(they compile them after the plugins) and forenforce: "pre"plugins withrollup. Withvite, Vite's own resolution and transforms run first. - With
vite, plugins apply to thenitroenvironment only, as bundler plugins: Vite-specific options and hooks (such asapplyorconfigureServer) are not supported. Add Vite plugins to Vite'spluginsinstead. - With
rspack, plugins run inside Rspack, which supportsresolveId,loadandtransform(receiving TypeScript and JSX untransformed),buildStart,buildEnd,renderChunk,generateBundle,writeBundleandcloseBundleand warns about other hooks. The plugin context is limited:this.emitFileonly emits assets (with asource),this.loadresolves to{ id, code },this.getModuleInfoonly has the ids of the importers and imports of a module,buildStartreceives no input options, and output chunks have no import, export or source map (map) information. In development,buildStartandcloseBundlerun for each rebuild.loadandtransformonly run for JavaScript and TypeScript modules (and virtual modules). - With
builder: false, plugins run in env-runner, which supports onlyresolveId,loadandtransform(with a limited plugin context) and warns about other hooks. Hooks only receive JavaScript and TypeScript modules unless theirfilternames other files (byidormoduleType), and files innode_modulesonly when it namesnode_modules.
export default defineConfig({
buildPlugins: [
{
name: "my-virtual-module",
resolveId: {
filter: { id: /^virtual:my-module$/ },
handler: (id) => `\0${id}`,
},
load: {
filter: { id: /^\0virtual:my-module$/ },
handler: () => `export default "Hello!"`,
},
},
],
});Nitro modules can add plugins with nitro.options.buildPlugins.push(plugin).
#rollupConfig
Additional rollup configuration.
export default defineConfig({
rollupConfig: {
output: { manualChunks: { vendor: ["lodash-es"] } },
},
});#rolldownConfig
Additional rolldown configuration.
export default defineConfig({
rolldownConfig: {
output: { banner: "/* built with nitro */" },
},
});#rspackConfig
Additional Rspack configuration (experimental rspack builder), merged with the one Nitro generates.
export default defineConfig({
builder: "rspack",
rspackConfig: {
optimization: { concatenateModules: false },
},
});#bunConfig
Additional Bun.build options for the bun builder.
export default defineConfig({
builder: "bun",
bunConfig: {
naming: { chunk: "chunks/[name]-[hash].mjs" },
},
});#vite
Options for the vite builder and the nitro/vite plugin.
path: Thevitepackage to use, as a path orfile://URL to its directory or entry (same asdeps.paths.vite). By default, thenitro/viteplugin uses the runningviteand thevitebuilder resolves it from the project root.assetsImport: Enable?assetsimports for collecting CSS and JS assets from entry points (default:true).serverReload: Reload the dev server (and the browser) when a server-only module changes (default:true).
export default defineConfig({
vite: {
path: import.meta.resolve("vite"),
},
});#services
- Type:
Record<string, { entry: string }> - Default:
{}
Server entries exporting a fetch handler, built in their own environment by the nitro/vite or nitro/rsbuild plugin and fetched with fetchService(name, input, init?) from nitro/services.
An ssr service is detected from an entry-server file in app/, src/ or the root of the project and server directories, and server environments with an entry are registered automatically. When no renderer is set, unmatched routes are rendered by the ssr service.
export default defineConfig({
services: { api: { entry: "./src/api-entry.ts" } },
});#deps
Options for the optional dependencies Nitro installs on demand (such as vite, rolldown, rollup, unstorage, db0 or unenv).
paths: Explicit packages to use, by package name. Each value is a path orfile://URL to the package directory or entry. Relative paths resolve againstrootDir.install: Whether a missing package may be installed (default:true, orfalsein CI). When disabled, the build fails with the command to add the missing package instead, so it only uses the dependencies committed to the project. Set it totrueto install on demand in CI too. The packages needed to load the config file itself (jiti,gigetanddotenvin runtimes without native support) are only installed outside of CI, whatever this option.
By default, these packages are resolved from your project and installed on demand when missing (except in CI). A framework built on top of Nitro can pass its own copies in deps.paths instead, so the versions it depends on are the ones that run. The server bundle uses them too for unstorage, db0 and unenv. An explicit package is never installed, and Nitro warns when its version is outside the supported range. Nothing is installed either when rootDir is inside node_modules (e.g. a framework using its own package directory): the framework has to declare the packages it uses in its own dependencies or pass them in deps.paths.
export default defineConfig({
deps: {
paths: {
unstorage: import.meta.resolve("unstorage"),
db0: import.meta.resolve("db0"),
},
},
});To never install them (also locally), disable install:
export default defineConfig({
deps: { install: false },
});deps.paths.vite is an alias of vite.path.
#entry
Bundler entry point.
export default defineConfig({
entry: "./server/entry.ts", // custom entry file
});#alias
Path aliases for module resolution.
export default defineConfig({
alias: {
"~utils": "./src/utils",
"#shared": "./shared",
},
});With the Vite builder, these aliases apply to every Vite environment. When Vite's resolve.alias (from the Vite config or another plugin, with a string find) maps the same key to another target, the Nitro target applies only to the nitro environment, and other environments (such as client and ssr) use the Vite target.
#inject
Globals to replace with imports when referenced in the bundle. Values are a module id (default export) or a [id, exportName] tuple.
Set a global to false to remove a default injection (e.g. one added for node: false builds).
export default defineConfig({
inject: {
Buffer: ["node:buffer", "Buffer"],
performance: false,
},
});#polyfills
Modules imported for their side effects before the server entry. Prefix an entry with ! to remove a default polyfill.
node: false builds add #nitro/runtime/polyfills/global, #nitro/runtime/polyfills/process, #nitro/runtime/polyfills/buffer and #nitro/runtime/polyfills/timers by default (e.g. "!#nitro/runtime/polyfills/timers" removes the setImmediate polyfill).
export default defineConfig({
polyfills: ["./polyfills/intl.ts"],
});#builtinModules
Modules provided by the target runtime, such as cloudflare:workers or node:fs on Deno. Imports of these ids are kept as-is in the output.
Builtin modules are never bundled, traced, or copied to the output, so only list modules that the runtime itself provides. To keep an npm package out of the bundle, use traceDeps instead. Node.js builtins are handled automatically when node is true.
Prefix an entry with ! to remove a default (e.g. one added by a preset).
export default defineConfig({
builtinModules: ["cloudflare:workers"],
});Note
Presets also add default alias, inject, polyfills, and builtinModules entries (for example, Cloudflare and Deno map Node.js builtins they support natively). Your own values in these options always take precedence.
The unenv option is deprecated. Presets passed to it still apply, after preset defaults and before your own options.
#minify
- Default:
false
Minify bundle.
Some presets (especially worker runtimes) enable minification by default. Set minify: false when debugging production, worker, or edge builds so stack traces stay readable.
export default defineConfig({
minify: true, // minify production bundle
});export default defineConfig({
minify: false, // easier to debug workers / edge bundles
});#inlineDynamicImports
- Default:
false
Bundle all code into a single file instead of creating separate chunks per route.
When false, each route handler becomes a separate chunk loaded on-demand. When true, everything is bundled together. Some presets enable this by default.
export default defineConfig({
inlineDynamicImports: true, // single output file
});#sourcemap
- Default:
false
Enable source map generation. See options.
export default defineConfig({
sourcemap: true, // generate .map files
});#node
- Default:
true
Specify whether the build is used for Node.js or not. If set to false, nitro adds default alias, inject and polyfills entries that polyfill Node.js globals and built-in modules (using unenv), and adjusts its behavior.
Node.js built-in modules that the target runtime does not provide (e.g. node:inspector on Cloudflare) are polyfilled with unenv. unenv is resolved from your project and installed on demand (except in CI, see deps.install), only when the build imports such a module.
export default defineConfig({
node: false, // target non-Node.js runtimes
});#replace
Build-time string replacements.
export default defineConfig({
replace: {
"process.env.APP_VERSION": JSON.stringify("1.0.0"),
},
});#commonJS
Specifies additional configuration for the rollup CommonJS plugin.
export default defineConfig({
commonJS: {
requireReturnsDefault: "auto",
},
});#exportConditions
Custom export conditions for module resolution.
export default defineConfig({
exportConditions: ["worker", "production"],
});#noExternals
- Default:
false
Prevent packages from being externalized. Externalized packages are imported at runtime instead of being bundled, so they do not see your alias configuration.
In a production build Nitro already bundles almost everything: only native or otherwise non-bundleable packages and the ones listed in traceDeps stay external. In development, dependencies inside node_modules are kept external for speed, which is where this option matters most.
Set it to true to bundle everything, including packages that are normally kept external:
export default defineConfig({
noExternals: true, // bundle all dependencies
});#Inlining specific packages
Pass an array to inline only some modules. RegExp entries are used as-is; string entries are escaped and matched as a path substring.
Each pattern is tested against the import specifier as written (for example @scope/my-lib) and against the resolved absolute file path (for example /…/node_modules/@scope/my-lib/dist/index.mjs). A match on either one keeps the module bundled, so a plain package name is usually all you need:
export default defineConfig({
alias: {
"@shared": "./shared",
},
noExternals: ["@scope/my-lib"],
});Use a path pattern when you need to be more precise, for example to inline one package in a monorepo without matching a similarly named one:
export default defineConfig({
noExternals: [/packages[\\/]my-lib/],
});Write [\\/] instead of / in such patterns so they also match Windows paths.
Note
In Nitro 2 this option was externals.inline.
#traceDeps
- Default:
[]
Additional dependencies to trace and include in the build output.
Supports special prefixes:
!pkg: Exclude a built-in package from tracing.pkg*: Full trace, copies all package files instead of only traced ones.
export default defineConfig({
traceDeps: [
"sharp",
"better-sqlite3",
"my-pkg*", // full trace (copy all package files)
"!unwanted-pkg", // exclude from tracing
],
});#traceOpts
Advanced options passed to nf3 for dependency tracing.
export default defineConfig({
traceOpts: {
// Options passed to @vercel/nft for file tracing
nft: { /* ... */ },
// Alias for module paths when tracing
traceAlias: { "old-pkg": "new-pkg" },
// Preserve or set file permissions when copying (true or octal like 0o755)
chmod: true,
// Transform traced files before copying
transform: [
{ filter: (id) => id.endsWith(".js"), handler: (code) => code },
],
// Hook into tracing lifecycle
hooks: {
tracedPackages(pkgs) {
console.log("Traced packages:", Object.keys(pkgs));
},
},
},
});#oxc
OXC options for the rollup builder. Includes minify and transform sub-options.
minify uses the minifier of rolldown. If rolldown is not installed, minification is skipped with a warning.
export default defineConfig({
oxc: {
minify: { compress: true, mangle: true },
},
});