Registry / web-framework / nitropack

nitropack

JSON →
library2.13.3jsnpmunverified

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.

npm install nitropack
INSTALL
IMPORT
SIG · NITROPACK
N
nitropack
web-frameworkjavascriptv2.13.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

defineNitroConfig
import { defineNitroConfig } from 'nitropack'
const defineNitroConfig = require('nitropack').defineNitroConfig
Primarily an ESM-first framework. CommonJS `require` is generally not recommended for modern Nitro projects.
defineEventHandler
import { defineEventHandler } from 'nitropack'
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
import { useRuntimeConfig } from 'nitropack'
import { runtimeConfig } from 'nitropack'
Used to access runtime configuration and environment variables. The function must be called, not directly accessed as an object.

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` */
nitropack --version
Debug
Known issues
breakingNitro 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.
affects: >=2.0.0
gotchaThe 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.
affects: >=2.0.0
breakingMultiple 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.
affects: <2.13.2
gotchaThe `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.
affects: >=2.0.0
Errors
Common errors & fixes
Error: Cannot find module 'nitropack/config'
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
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
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.
Upgrade
Version history
2.13.3latest on npm
Audit
Dependencies
xml2jsrequiredPeer dependency required for features that rely on XML parsing, particularly in certain deployment presets or configurations.
Agent activity
4 hits · last 30 days
node
4
Resources