Nitro Universal Server Framework

Common errors

• Error: Cannot find module 'h3'

  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.
  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.

• TypeError: eventHandler is not a function

  cause This usually happens when eventHandler (or defineEventHandler) is not correctly imported as a named export from 'nitro' or '#imports' during server build/runtime.
  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).

• Cannot read properties of undefined (reading 'runtimeConfig')

  cause Attempting to access useRuntimeConfig() outside of a Nitro event handler context, or before the Nitro app's configuration has been properly initialized.
  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.

• Rollup failed to resolve import '...'

  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.
  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.

Warnings

• breaking 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.
  Fix: Refer to the official Nitro v3 migration guide for detailed steps. Expect changes in configuration, build outputs, and potentially handler definitions.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install nitro-nightly npm
• yarn add nitro-nightly yarn
• pnpm add nitro-nightly pnpm

Imports

• defineEventHandler
  wrong:

  import { defineEventHandler } from 'h3';

  correct:

  import { defineEventHandler } from 'nitro';

  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
  wrong:

  import eventHandler from 'nitro';

  correct:

  import { eventHandler } from 'nitro';

  eventHandler is a named export and an alias for defineEventHandler, typically used for brevity.
• useRuntimeConfig
  wrong:

  import { useRuntimeConfig } from '#app';

  correct:

  import { useRuntimeConfig } from 'nitro';

  Provides access to the Nitro runtime configuration, including public and private variables. This is crucial for environments where config is injected at runtime.

Quickstart

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);
});