nitro

library0.0.0jsnpmunverified

Nitro is a robust server engine designed to extend Vite applications with production-ready, universal JavaScript servers that can be deployed across various platforms. Currently, Nitro v3 (`3.0.260415-beta`) is in beta, actively developed with highlights including experimental tracing channels, smarter dependency tracing, and an upgrade to H3 v2, which introduces web standard primitives. The stable version remains v2. Nitro differentiates itself by offering a zero-config experience, automatic file-system based routing for API endpoints, and a focus on performance with compile-time route processing, leading to minimal server bundles. It enables developers to build full-stack applications with capabilities like built-in task runners, scheduled cron jobs, and cross-environment WebSocket support. Releases are frequent, with beta versions seeing rapid iteration and stable versions receiving dependency updates and security fixes.

web-framework devops

npm install nitro

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NITRO

nitro

web-frameworkjavascriptv0.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineHandler

✓ import { defineHandler } from 'nitro'

✗ import { eventHandler } from 'nitro/h3'

For v3, `defineHandler` is the recommended way to define server routes, replacing `eventHandler` from `h3` directly or `nitropack/h3` in v2.

defineNitroConfig

✓ import { defineNitroConfig } from 'nitro/config'

✗ import { defineNitroConfig } from 'nitropack/config'

Used for defining Nitro-specific configuration. The import path changed from `nitropack/config` to `nitro/config` in v3 due to package rename.

useRuntimeConfig

✓ import { useRuntimeConfig } from 'nitro/runtime-config'

✗ import { useRuntimeConfig } from 'nitropack/runtime' // or: import { useRuntimeConfig } from 'nitro/runtime'

Accesses runtime configuration. The import path for `useRuntimeConfig` has been moved to `nitro/runtime-config` in v3, previously `nitropack/runtime` or `nitro/runtime` for earlier v3 betas.

This quickstart demonstrates how to set up a basic Nitro server with a configuration file, define a simple API route using `defineHandler`, and access both public and private runtime configurations.

/* nitro.config.ts */ import { defineNitroConfig } from 'nitro/config'; export default defineNitroConfig({ // Customize your Nitro app configuration here runtimeConfig: { // Public keys are exposed to the client-side. // Here, we define a secret key that will be accessible only on the server. apiSecret: process.env.API_SECRET ?? 'default_secret', public: { baseUrl: process.env.PUBLIC_BASE_URL ?? 'http://localhost:3000', }, }, // Define additional server directories if needed // srcDir: './server', }); /* server/api/hello.ts */ import { defineHandler } from 'nitro'; import { useRuntimeConfig } from 'nitro/runtime-config'; export default defineHandler(async (event) => { const config = useRuntimeConfig(event); // Access the server-only secret const secret = config.apiSecret; // Access a public config value const baseUrl = config.public.baseUrl; return { message: `Hello from Nitro API! Your base URL is ${baseUrl}`, secretRevealed: `Shhh, the secret is: ${secret}`, }; });

nitro --version

Debug

Known issues

breakingNitro v3 introduces significant breaking changes, including package rename from `nitropack` to `nitro`, updated import paths (e.g., `nitropack/config` to `nitro/config`), `eventHandler` renamed to `defineHandler`, and `createError` to `HTTPError`.

fix

Refer to the official Nitro v3 migration guide for a comprehensive list of changes and updated code patterns. Update package names and import paths accordingly.

affects: >=3.0.0-alpha.0

breakingNitro v3 requires Node.js version 20 or higher. Support for Node.js 14 and 16 has been completely dropped. Deployments and local development environments must be upgraded.

fix

Ensure your Node.js environment (local, CI/CD, hosting provider) is updated to Node.js 20 LTS or a later compatible version.

affects: >=3.0.0-alpha.0

breakingThe `app.config.ts` and `useAppConfig()` functionality from Nitro v2 has been entirely removed in v3.

fix

Migrate configuration to use `nitro.config.ts` and `useRuntimeConfig()` or import regular `.ts` files from your `server` directory directly.

affects: >=3.0.0-alpha.0

gotchaNitro v3 is currently in beta. While actively developed and nearing a stable release, its APIs and features can still change. It serves as the foundation for Nuxt 5, which will ship with Nitro v3 once it's stable.

fix

Monitor official releases and the migration guide regularly. Be prepared for potential API adjustments if using beta versions in production-like environments.

affects: 3.x.x-beta

gotchaThe `useRuntimeConfig` import path has been unstable during v3 beta, moving from `nitropack/runtime` to `nitro/runtime` and then to `nitro/runtime-config`.

fix

Always use the latest documented import path for `useRuntimeConfig`: `import { useRuntimeConfig } from 'nitro/runtime-config'`. Explicitly import it, as auto-import might not correctly resolve older paths.

affects: 3.x.x-beta

Errors

Common errors & fixes

Cannot find module 'nitropack'

Attempting to import from the old `nitropack` package name after upgrading to Nitro v3.

fix

Rename `nitropack` dependency to `nitro` in `package.json` and update all imports from `nitropack/*` to `nitro/*`.

HTTPError: useRuntimeConfig is not defined

Incorrect or missing import for `useRuntimeConfig` in Nitro v3, or using an outdated import path.

fix

Ensure you explicitly `import { useRuntimeConfig } from 'nitro/runtime-config'` in your server-side files.

ReferenceError: eventHandler is not defined

Using the v2 `eventHandler` function in a Nitro v3 project, where it has been renamed.

fix

Replace `eventHandler` with `defineHandler` and ensure it's imported correctly: `import { defineHandler } from 'nitro'`.

Module level directives cause errors when bundled, 'use client' nature

CommonJS packages, particularly those with bare runtime detections, can break with Nitro v3's ESM-first approach.

fix

Ensure all dependencies are compatible with ESM or investigate using Nitro's experimental features related to dependency tracing and `nf3` improvements to better handle native packages and optional dependencies.

Upgrade

Version history

0.0.0latest on npm

Audit

Dependencies

viterequiredCore integration for extending Vite applications with server capabilities.

h3requiredUnderlying HTTP framework for defining server routes and handlers, upgraded to v2 in Nitro v3.

rolluprequiredUsed for bundling server routes and optimizing output, essential for production builds.

dotenvoptionalCommonly used for loading environment variables in development, though Nitro has its own runtime config mechanisms.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nitrojs/nitro ↗

packagehttps://www.npmjs.com/package/nitro ↗

homepagehttps://nitro.unjs.io ↗