{"id":15471,"library":"nitro-nightly","title":"Nitro Universal Server Framework","description":"Nitro is a versatile framework for building and deploying universal JavaScript servers, extending existing Vite applications with production-ready server capabilities. The `nitro-nightly` package represents the active development line for Nitro v3, which is currently in beta. Nitro v3 aims for a significantly smaller install size (down to 9MB), near-native runtime performance, and enhanced features like experimental tracing channels and smarter dependency tracing. While the stable release series remains v2, `nitro-nightly` provides access to cutting-edge features and improvements for upcoming major versions. Nitro focuses on a \"run anywhere\" philosophy, abstracting deployment complexities, and often offers a zero-configuration experience for common use cases. New `nitro-nightly` releases are frequent, reflecting active development and testing against real-world projects.","status":"active","version":"3.0.1-20260420-010726-8c3f16b2","language":"javascript","source_language":"en","source_url":"https://github.com/nitrojs/nitro","tags":["javascript","api-routes","full-stack","h3","nitro","server","typescript","vite","vite-plugin"],"install":[{"cmd":"npm install nitro-nightly","lang":"bash","label":"npm"},{"cmd":"yarn add nitro-nightly","lang":"bash","label":"yarn"},{"cmd":"pnpm add nitro-nightly","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler for optimizing and packaging server code.","package":"rollup","optional":false},{"reason":"Essential for integration with Vite-based applications and leveraging its build ecosystem.","package":"vite","optional":false},{"reason":"Used for integrating with Vercel's queueing services, only needed for Vercel deployments.","package":"@vercel/queue","optional":true},{"reason":"For loading environment variables from .env files, often used in development or specific deployment setups.","package":"dotenv","optional":true},{"reason":"A utility for scaffolding new projects or generating files, not a runtime dependency.","package":"giget","optional":true},{"reason":"Used for dynamic module loading and CommonJS/ESM interoperability, primarily for internal tooling or specific build configurations.","package":"jiti","optional":true},{"reason":"A utility for parsing XML, only needed if your server handles XML data.","package":"xml2js","optional":true},{"reason":"A specific agent, likely for monitoring or integration, only needed if explicitly configured.","package":"zephyr-agent","optional":true}],"imports":[{"note":"While originating from h3, Nitro re-exports defineEventHandler. Using 'nitro' or '#imports' ensures proper integration within the Nitro context, including auto-imports and build-time optimizations.","wrong":"import { defineEventHandler } from 'h3';","symbol":"defineEventHandler","correct":"import { defineEventHandler } from 'nitro';"},{"note":"eventHandler is a named export and an alias for defineEventHandler, typically used for brevity.","wrong":"import eventHandler from 'nitro';","symbol":"eventHandler","correct":"import { eventHandler } from 'nitro';"},{"note":"Provides access to the Nitro runtime configuration, including public and private variables. This is crucial for environments where config is injected at runtime.","wrong":"import { useRuntimeConfig } from '#app';","symbol":"useRuntimeConfig","correct":"import { useRuntimeConfig } from 'nitro';"}],"quickstart":{"code":"import { defineEventHandler, createApp, toNodeListener, useRuntimeConfig } from 'nitro';\nimport { listen } from 'listhen';\n\n// Define a simple server route\nconst helloHandler = defineEventHandler(() => {\n  const message = 'Hello from Nitro!';\n  const date = new Date().toISOString();\n  // Example of using runtime config (though not explicitly set here)\n  const secretKey = process.env.MY_SECRET_KEY ?? 'default_secret';\n  console.log(`Request received at ${date}. Using secret: ${secretKey}`);\n  return { api: message, timestamp: date, secretUsed: secretKey };\n});\n\nconst userHandler = defineEventHandler((event) => {\n  const name = event.context.params?.name || 'Guest';\n  return { message: `Hello, ${name}!` };\n});\n\n// Create a Nitro application\nconst app = createApp();\n\n// Add routes to the app\napp.router.get('/', helloHandler);\napp.router.get('/api/hello/:name', userHandler);\napp.router.get('/api/config', defineEventHandler(() => {\n  const config = useRuntimeConfig(); // Access runtime config\n  return {\n    public: config.public,\n    serverSecret: config.serverSecret // Example of a server-only secret\n  };\n}));\n\n// Define configuration for the server\nconst serverConfig = {\n  host: process.env.HOST || '0.0.0.0',\n  port: parseInt(process.env.PORT || '3000')\n};\n\n// Start the server\nasync function startServer() {\n  const listener = toNodeListener(app);\n  console.log(`Nitro server running on http://${serverConfig.host}:${serverConfig.port}`);\n  await listen(listener, serverConfig);\n}\n\nstartServer().catch((error) => {\n  console.error('Failed to start Nitro server:', error);\n  process.exit(1);\n});","lang":"typescript","description":"This quickstart demonstrates how to create a basic Nitro server, define multiple API routes using defineEventHandler, access request parameters, and start the server. It also shows a placeholder for accessing runtime configuration."},"warnings":[{"fix":"Refer to the official Nitro v3 migration guide for detailed steps. Expect changes in configuration, build outputs, and potentially handler definitions.","message":"Nitro v3 (represented by nitro-nightly) introduces significant architectural changes and API adjustments compared to the stable v2 series. Existing v2 projects will require migration efforts.","severity":"breaking","affected_versions":">=3.0.0-alpha"},{"fix":"For stable production applications, use the latest official release of Nitro v2 (e.g., 'nitro' npm package). Use 'nitro-nightly' only for testing upcoming features or contributing to development.","message":"The 'nitro-nightly' package is a pre-release channel for Nitro v3 development. It is not intended for production use due to potential instabilities, frequent API changes, and lack of long-term support.","severity":"gotcha","affected_versions":">=3.0.0-alpha"},{"fix":"Ensure you are on Nitro v2.13.3 or higher to benefit from the latest h3 security patches. For v3, ensure you are on the latest 'nitro-nightly' as it will include updated h3 versions.","message":"Multiple h3 security fixes have been released, particularly in h3 versions 1.15.5 and 1.15.9. Older Nitro versions might be vulnerable if using an unpatched h3 dependency.","severity":"breaking","affected_versions":"<2.13.3"},{"fix":"Avoid relying on experimental features in critical paths unless you are prepared for rapid iteration and potential breaking changes. Monitor release notes closely for updates on experimental APIs.","message":"New experimental features, such as tracing channels, are introduced in Nitro v3. These features may change significantly or be removed in future pre-releases without prior notice.","severity":"gotcha","affected_versions":">=3.0.0-beta"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure 'h3' is listed as a direct or transitive dependency. Run 'npm install h3' or 'yarn add h3' if it's missing, or check your lock file for correct resolution.","cause":"The h3 dependency, while used by Nitro, might not be correctly resolved or installed, especially in complex monorepos or with non-standard package managers.","error":"Error: Cannot find module 'h3'"},{"fix":"Verify the import statement: 'import { eventHandler } from 'nitro';'. Also, ensure Nitro's auto-imports are correctly configured in your project (e.g., in nuxt.config.ts if used with Nuxt).","cause":"This usually happens when eventHandler (or defineEventHandler) is not correctly imported as a named export from 'nitro' or '#imports' during server build/runtime.","error":"TypeError: eventHandler is not a function"},{"fix":"Ensure useRuntimeConfig() is called within a defineEventHandler or eventHandler function. Verify that your Nitro configuration (nitro.config.ts) is properly set up with a 'runtimeConfig' object.","cause":"Attempting to access useRuntimeConfig() outside of a Nitro event handler context, or before the Nitro app's configuration has been properly initialized.","error":"Cannot read properties of undefined (reading 'runtimeConfig')"},{"fix":"Check your 'nitro.config.ts' for 'externals' or 'rollup' options. You might need to add the failing module to 'rollup.options.external' or ensure it's correctly installed and available in your build environment.","cause":"Nitro's build process, powered by Rollup, could not find an imported module. This often happens with third-party dependencies that are not properly bundled or externalized.","error":"Rollup failed to resolve import '...'"}],"ecosystem":"npm"}