Nitro (Universal JavaScript Servers)

2.13.3 · maintenance · verified Sun Apr 19

Nitro is a powerful framework for building universal JavaScript servers, enabling developers to write code once and deploy it across various environments including Node.js, serverless platforms, and edge functions. The current stable version is v2.13.3, which is maintained with regular dependency updates and critical security fixes. Active development is focused on the upcoming v3 beta, which promises further performance enhancements and features. Key differentiators include its "run anywhere" philosophy, exceptional runtime performance (approaching native levels on platforms like Bun), and a minimal install footprint. It integrates deeply with ecosystem tools like Nuxt and provides advanced features such as experimental tracing channels and smarter dependency tracing, ensuring timely updates and security patches.

Common errors

```
Error: Cannot find module 'nitropack/config'
```
cause This error typically indicates that the `nitro.config.ts` (or `.js`) file is missing or incorrectly named in your project root, or the build process cannot locate it.

fix Ensure you have a `nitro.config.ts` (or `.js`) file in your project's root directory. If it exists, verify its contents and path, and ensure your build command is run from the correct directory.
```
TypeError: defineEventHandler is not a function
```
cause This usually occurs when attempting to use a CommonJS `require` statement instead of an ESM `import` for `defineEventHandler`, or incorrectly attempting a default import.

fix Ensure you are using `import { defineEventHandler } from 'nitropack'` in your server files, and that your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
ReferenceError: useRuntimeConfig is not defined
```
cause The `useRuntimeConfig` function was not imported or is being called outside of an appropriate context where Nitro's runtime is available.

fix Add `import { useRuntimeConfig } from 'nitropack'` to the top of your file. Ensure you are calling this function within a server handler or plugin where the Nitro context is initialized.

Warnings

breaking Nitro v3 is currently in active beta development. Users on v2 (maintenance branch) should anticipate significant breaking changes and API differences when migrating to v3. Consult the v3 documentation and migration guides for detailed upgrade paths.
Fix: For new projects, consider starting with Nitro v3 beta if compatible with your ecosystem. For existing v2 projects, thoroughly review v3 migration guides before upgrading.
gotcha The official documentation and main development focus are shifting towards the v3 branch. Users working with the `nitropack` npm package (v2.x.x) are on the v2 support branch, which receives maintenance and critical updates, but not the latest features.
Fix: To access the latest features and performance improvements, check out the `v3` branch on GitHub and follow its development. Be aware that v3 is pre-release software.
breaking Multiple security vulnerabilities in the underlying `h3` library (v1.15.5 and v1.15.9) were addressed in Nitro v2.13.1 and v2.13.2 respectively. Older versions of Nitro are vulnerable.
Fix: Upgrade to `nitropack@2.13.2` or later immediately to incorporate these crucial security patches.
gotcha The `xml2js` package is listed as a peer dependency. If your Nitro project utilizes features that require XML parsing, this package must be installed separately.
Fix: Ensure `xml2js` is installed in your project: `npm install xml2js` or `pnpm add xml2js` if you encounter issues related to XML processing.

Install

npm install nitropack npm
yarn add nitropack yarn
pnpm add nitropack pnpm

Imports

defineNitroConfig
wrong:
```
const defineNitroConfig = require('nitropack').defineNitroConfig
```
correct:
```
import { defineNitroConfig } from 'nitropack'
```
Primarily an ESM-first framework. CommonJS `require` is generally not recommended for modern Nitro projects.
defineEventHandler
wrong:
```
import defineEventHandler from 'nitropack'
```
correct:
```
import { defineEventHandler } from 'nitropack'
```
This is a named export. Attempting a default import will result in an undefined symbol. Used for defining server routes.
useRuntimeConfig
wrong:
```
import { runtimeConfig } from 'nitropack'
```
correct:
```
import { useRuntimeConfig } from 'nitropack'
```
Used to access runtime configuration and environment variables. The function must be called, not directly accessed as an object.

Quickstart

This quickstart demonstrates how to configure Nitro, define a basic API route using `defineEventHandler`, and access runtime configuration using `useRuntimeConfig`.

import { defineNitroConfig, defineEventHandler, useRuntimeConfig } from 'nitropack';

// nitro.config.ts
export default defineNitroConfig({
  preset: 'node', // Choose your deployment target: 'vercel', 'netlify', 'cloudflare', 'bun', etc.
  output: {
    dir: '.output', // Default output directory for the build artifacts
    publicDir: '.output/public' // Directory for static assets
  },
  // Environment variables can be exposed to the runtime here
  runtimeConfig: {
    apiSecret: process.env.API_SECRET ?? 'default_secret', // Accessible via useRuntimeConfig()
  },
  // Define a simple route directly in the config (alternative to server/ directory)
  routes: {
    '/inline-hello': 'Hello from inline route!'
  }
});

// server/api/hello.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();
  return {
    message: 'Hello from Nitro API!',
    timestamp: new Date().toISOString(),
    apiSecretPartial: config.apiSecret.substring(0, 5) + '...', // Accessing runtime config
    path: event.path
  };
});

/*
To run this example:
1. Create a `nitro.config.ts` file with the above configuration.
2. Create a `server/api/hello.ts` file with the event handler.
3. Install dependencies: `npm install nitropack xml2js` (xml2js is a peer dep).
4. Build the project: `npx nitro build`
5. Start the server: `node .output/server/index.mjs`
6. Access in browser: `http://localhost:3000/api/hello` and `http://localhost:3000/inline-hello`
*/

view raw JSON →