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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
defineEventHandler
✓ import { defineEventHandler } from 'nitro';
✗ import { defineEventHandler } from 'h3';
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.
eventHandler
✓ import { eventHandler } from 'nitro';
✗ import eventHandler from 'nitro';
eventHandler is a named export and an alias for defineEventHandler, typically used for brevity.
useRuntimeConfig
✓ import { useRuntimeConfig } from 'nitro';
✗ import { useRuntimeConfig } from '#app';
Provides access to the Nitro runtime configuration, including public and private variables. This is crucial for environments where config is injected at runtime.
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.
import { defineEventHandler, createApp, toNodeListener, useRuntimeConfig } from 'nitro';
import { listen } from 'listhen';
// Define a simple server route
const helloHandler = defineEventHandler(() => {
const message = 'Hello from Nitro!';
const date = new Date().toISOString();
// Example of using runtime config (though not explicitly set here)
const secretKey = process.env.MY_SECRET_KEY ?? 'default_secret';
console.log(`Request received at ${date}. Using secret: ${secretKey}`);
return { api: message, timestamp: date, secretUsed: secretKey };
});
const userHandler = defineEventHandler((event) => {
const name = event.context.params?.name || 'Guest';
return { message: `Hello, ${name}!` };
});
// Create a Nitro application
const app = createApp();
// Add routes to the app
app.router.get('/', helloHandler);
app.router.get('/api/hello/:name', userHandler);
app.router.get('/api/config', defineEventHandler(() => {
const config = useRuntimeConfig(); // Access runtime config
return {
public: config.public,
serverSecret: config.serverSecret // Example of a server-only secret
};
}));
// Define configuration for the server
const serverConfig = {
host: process.env.HOST || '0.0.0.0',
port: parseInt(process.env.PORT || '3000')
};
// Start the server
async function startServer() {
const listener = toNodeListener(app);
console.log(`Nitro server running on http://${serverConfig.host}:${serverConfig.port}`);
await listen(listener, serverConfig);
}
startServer().catch((error) => {
console.error('Failed to start Nitro server:', error);
process.exit(1);
});
nitro --version
Errors
Common errors & fixes
Error: Cannot find module 'h3'
The h3 dependency, while used by Nitro, might not be correctly resolved or installed, especially in complex monorepos or with non-standard package managers.
fixEnsure '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.
TypeError: eventHandler is not a function
This usually happens when eventHandler (or defineEventHandler) is not correctly imported as a named export from 'nitro' or '#imports' during server build/runtime.
fixVerify 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). Cannot read properties of undefined (reading 'runtimeConfig')
Attempting to access useRuntimeConfig() outside of a Nitro event handler context, or before the Nitro app's configuration has been properly initialized.
fixEnsure 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.
Rollup failed to resolve import '...'
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.
fixCheck 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.
Upgrade
Version history
3.0.1-20260420-010726-8c3f16b2latest on npm
Audit
Dependencies
rolluprequiredCore bundler for optimizing and packaging server code.
viterequiredEssential for integration with Vite-based applications and leveraging its build ecosystem.
@vercel/queueoptionalUsed for integrating with Vercel's queueing services, only needed for Vercel deployments.
dotenvoptionalFor loading environment variables from .env files, often used in development or specific deployment setups.
gigetoptionalA utility for scaffolding new projects or generating files, not a runtime dependency.
jitioptionalUsed for dynamic module loading and CommonJS/ESM interoperability, primarily for internal tooling or specific build configurations.
xml2jsoptionalA utility for parsing XML, only needed if your server handles XML data.
zephyr-agentoptionalA specific agent, likely for monitoring or integration, only needed if explicitly configured.