TypeScript

Nitro is written in TypeScript and bundles your server code — .ts files work out of the box in development and production, with no separate compile step. The TypeScript compiler is only needed for type checking (for example tsc --noEmit in CI).

All public utilities ship with types:

import { defineConfig } from "nitro";

export default defineConfig({
  // Fully typed config with completions
});

import { defineHandler } from "nitro";

export default defineHandler((event) => {
  return { hello: "world" }; // Typed event and inferred return type
});

Types (such as NitroConfig, NitroModule, or NitroRuntimeConfig) are exported from nitro/types:

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

tsconfig.json setup

Nitro provides a shareable TypeScript configuration you can extend from:

{
  "extends": "nitro/tsconfig"
}

It enables modern, strict defaults matching how Nitro bundles your code: strict type checking, bundler module resolution, noEmit, verbatimModuleSyntax, and allowImportingTsExtensions (so you can use explicit .ts extensions in imports). You can override any option by adding your own compilerOptions on top:

{
  "extends": "nitro/tsconfig",
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

Generated types

Nitro generates project-specific type declarations based on your routes and configuration. They are written automatically when the dev server starts and on every build, or on demand with nitro prepare.

The files are written to the generated types directory — node_modules/.nitro/types by default (configurable via typescript.generatedTypesDir):

To make them available to your editor and type checker, add the entry file to your tsconfig include (the explicit path is required since node_modules is excluded by default):

{
  "extends": "nitro/tsconfig",
  "include": ["node_modules/.nitro/types/nitro.d.ts", "**/*"]
}

Route types

For each scanned route handler, Nitro records the (JSON-serialized) return type in the InternalApi interface of nitro/types, keyed by route path and HTTP method. Frameworks and libraries can build on this augmentation — together with helper types such as NitroFetchRequest and TypedInternalResponse from nitro/types — to provide end-to-end typed clients for your API.

Runtime config types

By default, useRuntimeConfig() returns a loosely typed object. Enable typescript.generateRuntimeConfigTypes to generate a NitroRuntimeConfig interface from the runtimeConfig values in your config:

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    apiToken: "dev-token", // Overridable with the NITRO_API_TOKEN environment variable
  },
  typescript: {
    generateRuntimeConfigTypes: true,
  },
});

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

export default defineHandler(() => {
  const config = useRuntimeConfig();
  return { token: config.apiToken }; // Typed as string
});

typescript config options

With generateTsConfig: true, Nitro writes a complete tsconfig.json to the generated types directory — already wired to the generated declarations, your project files, and any tsConfig overrides. You can extend it instead of nitro/tsconfig:

{
  "extends": "./node_modules/.nitro/types/tsconfig.json"
}

Auto-imports

Auto-imports are disabled by default in Nitro v3 — explicit imports are recommended for better ecosystem compatibility and clarity. See the migration guide for the list of utilities and where to import them from.

If you prefer auto-imports, opt in by setting the imports option (an object enables them):

import { defineConfig } from "nitro";

export default defineConfig({
  serverDir: true,
  imports: {},
});

When enabled, exports from the utils/ directory of scanned directories (for example server/utils/) are automatically available in your server code without imports. The imports object accepts unimport options (dirs, presets, exclude, ...) for further customization.

Type declarations for auto-imported utilities are written to nitro-imports.d.ts in the generated types directory — make sure it is referenced from your tsconfig as shown in generated types so your editor recognizes the globals.

Extending types from modules

Modules can hook into type generation with the types:extend build-time hook, which receives the collected types before the declaration files are written:

import { defineConfig } from "nitro";

export default defineConfig({
  modules: [
    (nitro) => {
      nitro.hooks.hook("types:extend", (types) => {
        types.routes["/api/external"] = { default: ["{ data: string }"] };
      });
    },
  ],
});

The types object contains the per-route type expressions (types.routes) and, when generateTsConfig is enabled, the generated tsconfig (types.tsConfig).