Skip to content

Latest commit

 

History

History
120 lines (81 loc) · 4.07 KB

00.migration.md

File metadata and controls

120 lines (81 loc) · 4.07 KB
icon
ri:arrow-right-up-line

Migration Guide

Note

This is a living document for migrating from Nitro 2 to 3. Please check it regularly while using the beta version.

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:

Note

Currently, only nightly releases are available.

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

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.

Old Preset New Preset
node node-middleware (export changed to middleware)
cloudflare, cloudflare_worker, cloudflare_module_legacy cloudflare_module
deno-server-legacy deno_server with Deno v2
netlify-builder netlify_functions or netlify_edge
vercel-edge vercel with Fluid compute enabled
azure, azure_functions azure_swa
firebase firebase-functions
iis iis-handler
deno deno-deploy
edgio layer0
cli Removed due to lack of use
service_worker Removed due to instability

Removed Subpath Exports

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

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

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