Migration Guide

Nitro v3 introduces intentional backward-incompatible changes. This guide helps you migrate from Nitro v2.

nitropack is renamed to nitro

The NPM package nitropack (v2) has been renamed to nitro (v3).

Migration: Update the nitropack dependency to nitro in package.json:

{
  "dependencies": {
--    "nitropack": "latest"
++    "nitro": "latest"
  }
}

{
  "dependencies": {
--    "nitropack": "latest"
++    "nitro": "npm:nitro-nightly"
  }
}

Migration: Search your codebase and rename all instances of nitropack to nitro:

-- import { defineNitroConfig } from "nitropack/config"
++ import { defineNitroConfig } from "nitro/config"

nitro/runtime/*

Previously, you could import from both nitro/runtime and nitro/runtime/*.

Support for nested paths has been removed to prevent exposing Nitro internals.

Migration: Search for nitro/runtime/ imports and replace them with nitro/runtime:

-- import { useStorage } from "nitropack/runtime/storage"
++ import { useStorage } from "nitro/runtime"

Minimum Supported Node.js Version: 20

Nitro now requires a minimum Node.js version of 20, as Node.js 18 reaches end-of-life in April 2025.

Please upgrade to the latest LTS version (>= 20).

Migration:

• Check your local Node.js version using node --version and update if necessary.
• If you use a CI/CD system for deployment, ensure that your pipeline is running Node.js 20 or higher.
• If your hosting provider manages the Node.js runtime, make sure it’s set to version 20, 22, or later.

Type Imports

Nitro types are now only exported from nitro/types.

Migration: Import types from nitro/types instead of nitro:

-- import { NitroRuntimeConfig } from "nitropack"
++ import { NitroRuntimeConfig } from "nitro/types"

App Config Support Removed

Nitro v2 supported a bundled app config that allowed defining configurations in app.config.ts and accessing them at runtime via useAppConfig().

This feature had been removed.

Migration:

Use a regular .ts file in your server directory and import it directly.

Preset updates

Nitro presets have been updated for the latest compatibility.

Some (legacy) presets have been removed or renamed.

Changed nitro subpath imports

Nitro v2 introduced multiple subpath exports, some of which have been removed or updated:

• nitropack/core (use nitro/builder)
• nitropack/runtime/* (use nitro/runtime)
• nitropack/dist/runtime/* (use nitro/runtime)
• nitro/rollup (use nitro/builder)
• nitropack/kit (removed)
• nitropack/presets (removed)

An experimental nitropack/kit was introduced but has now been removed. A standalone Nitro Kit package may be introduced in the future with clearer objectives.

Migration:

• Use NitroModule from nitro/types instead of defineNitroModule from the kit.
• Prefer built-in Nitro presets (external presets are only for evaluation purposes).

Optional Hooks

If you were using useNitroApp().hooks outside of Nitro plugins before, it might be undefined. Use new useNitroHooks() to guarantee having an instance.