{"id":11398,"library":"nitropack","title":"Nitro (Universal JavaScript Servers)","description":"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.","status":"maintenance","version":"2.13.3","language":"javascript","source_language":"en","source_url":"https://github.com/nitrojs/nitro","tags":["javascript","typescript"],"install":[{"cmd":"npm install nitropack","lang":"bash","label":"npm"},{"cmd":"yarn add nitropack","lang":"bash","label":"yarn"},{"cmd":"pnpm add nitropack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for features that rely on XML parsing, particularly in certain deployment presets or configurations.","package":"xml2js","optional":false}],"imports":[{"note":"Primarily an ESM-first framework. CommonJS `require` is generally not recommended for modern Nitro projects.","wrong":"const defineNitroConfig = require('nitropack').defineNitroConfig","symbol":"defineNitroConfig","correct":"import { defineNitroConfig } from 'nitropack'"},{"note":"This is a named export. Attempting a default import will result in an undefined symbol. Used for defining server routes.","wrong":"import defineEventHandler from 'nitropack'","symbol":"defineEventHandler","correct":"import { defineEventHandler } from 'nitropack'"},{"note":"Used to access runtime configuration and environment variables. The function must be called, not directly accessed as an object.","wrong":"import { runtimeConfig } from 'nitropack'","symbol":"useRuntimeConfig","correct":"import { useRuntimeConfig } from 'nitropack'"}],"quickstart":{"code":"import { defineNitroConfig, defineEventHandler, useRuntimeConfig } from 'nitropack';\n\n// nitro.config.ts\nexport default defineNitroConfig({\n  preset: 'node', // Choose your deployment target: 'vercel', 'netlify', 'cloudflare', 'bun', etc.\n  output: {\n    dir: '.output', // Default output directory for the build artifacts\n    publicDir: '.output/public' // Directory for static assets\n  },\n  // Environment variables can be exposed to the runtime here\n  runtimeConfig: {\n    apiSecret: process.env.API_SECRET ?? 'default_secret', // Accessible via useRuntimeConfig()\n  },\n  // Define a simple route directly in the config (alternative to server/ directory)\n  routes: {\n    '/inline-hello': 'Hello from inline route!'\n  }\n});\n\n// server/api/hello.ts\nexport default defineEventHandler(async (event) => {\n  const config = useRuntimeConfig();\n  return {\n    message: 'Hello from Nitro API!',\n    timestamp: new Date().toISOString(),\n    apiSecretPartial: config.apiSecret.substring(0, 5) + '...', // Accessing runtime config\n    path: event.path\n  };\n});\n\n/*\nTo run this example:\n1. Create a `nitro.config.ts` file with the above configuration.\n2. Create a `server/api/hello.ts` file with the event handler.\n3. Install dependencies: `npm install nitropack xml2js` (xml2js is a peer dep).\n4. Build the project: `npx nitro build`\n5. Start the server: `node .output/server/index.mjs`\n6. Access in browser: `http://localhost:3000/api/hello` and `http://localhost:3000/inline-hello`\n*/","lang":"typescript","description":"This quickstart demonstrates how to configure Nitro, define a basic API route using `defineEventHandler`, and access runtime configuration using `useRuntimeConfig`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `nitropack@2.13.2` or later immediately to incorporate these crucial security patches.","message":"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.","severity":"breaking","affected_versions":"<2.13.2"},{"fix":"Ensure `xml2js` is installed in your project: `npm install xml2js` or `pnpm add xml2js` if you encounter issues related to XML processing.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Cannot find module 'nitropack/config'"},{"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`).","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.","error":"TypeError: defineEventHandler is not a function"},{"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.","cause":"The `useRuntimeConfig` function was not imported or is being called outside of an appropriate context where Nitro's runtime is available.","error":"ReferenceError: useRuntimeConfig is not defined"}],"ecosystem":"npm"}