Server Utilities

Nitro has no auto-imports: every utility must be explicitly imported from the main nitro entry or one of its subpaths. This page maps each export to its import path.

Quick reference

nitro

The main entry contains everything you need for day-to-day route handlers.

Commonly used types are also exported: H3Event, EventHandlerRequest, and EventHandlerWithFetch.

import { defineHandler, HTTPError } from "nitro";

export default defineHandler((event) => {
  const name = event.url.searchParams.get("name");
  if (!name) {
    throw new HTTPError("Missing name", { status: 400 });
  }
  return { hello: name };
});

Internal fetch

serverFetch calls a route of your own app directly — the request goes through the Nitro app (route rules, middleware, plugins) without touching the network:

import { defineHandler, serverFetch } from "nitro";

export default defineHandler(async () => {
  const res = await serverFetch("/api/stats"); // returns a web Response
  return { stats: await res.json() };
});

The fetch export is a universal variant: absolute paths (starting with /) are handled internally via serverFetch, everything else falls back to global fetch:

import { fetch } from "nitro";

await fetch("/api/hello"); // handled by your own server
await fetch("https://example.com"); // regular network fetch

Error handler

Point the errorHandler config to a file that exports a custom error handler:

import { defineErrorHandler } from "nitro";

export default defineErrorHandler((error, event) => {
  return new Response(`[custom error] ${error.message}`, {
    status: error.status,
    headers: { "Content-Type": "text/plain" },
  });
});

Runtime plugins

Plugins run once on server startup and can hook into the runtime lifecycle:

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("request", (event) => {
    console.log("request:", event.url.pathname);
  });
});

See the plugins guide for more.

nitro/h3

Re-exports all H3 v2 utilities: readBody, getQuery, getCookie, setCookie, proxy, redirect, and many more.

import { defineHandler } from "nitro";
import { readBody, getCookie } from "nitro/h3";

export default defineHandler(async (event) => {
  const body = await readBody(event);
  const session = getCookie(event, "session");
  return { body, session };
});

nitro/cache

import { defineCachedHandler } from "nitro/cache";

export default defineCachedHandler(() => `Generated at ${new Date().toISOString()}`, {
  maxAge: 60,
});

See the cache guide for options, cache keys, and invalidation.

nitro/storage

import { useStorage } from "nitro/storage";

await useStorage("data").set("visits", 42);

See the KV storage guide for mountpoints and drivers.

nitro/database

import { useDatabase } from "nitro/database";

const db = useDatabase();
const { rows } = await db.sql`SELECT * FROM users`;

See the database guide for connectors and configuration.

nitro/runtime-config

import { useRuntimeConfig } from "nitro/runtime-config";

const { apiToken } = useRuntimeConfig();

nitro/task

import { runTask } from "nitro/task";

const { result } = await runTask("db:migrate", { payload: { force: true } });

See the tasks guide — tasks are experimental and require the experimental.tasks flag.

nitro/app

Lower-level access to the running Nitro app.

import { useNitroHooks } from "nitro/app";

useNitroHooks().hook("error", (error) => {
  console.error(error);
});

nitro/context

import { useRequest } from "nitro/context";

const request = useRequest();

nitro/config

Prefer importing defineConfig from "nitro" directly.

nitro/types

Type-only entry with all public Nitro types, including NitroConfig, Nitro, NitroApp, NitroAppPlugin, NitroErrorHandler, NitroRuntimeConfig, NitroRuntimeHooks, and Task.

import type { NitroRuntimeConfig } from "nitro/types";

nitro/vite

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [nitro()],
});

The NitroPluginConfig and ServiceConfig types are also exported. See the Vite integration guide.

Other entries

The remaining subpaths (nitro/meta for package version and paths, nitro/builder, nitro/vite/runtime, nitro/tsconfig) are internal and rarely needed in application code.