|
| 1 | +--- |
| 2 | +icon: ri:arrow-right-up-line |
| 3 | +--- |
| 4 | + |
| 5 | +# Migration Guide |
| 6 | + |
| 7 | +> [!NOTE] |
| 8 | +> This is a living document for migrating from Nitro 2 to 3. Please check it regularly while using the beta version. |
| 9 | +
|
| 10 | +Nitro v3 introduces intentional backward-incompatible changes. This guide helps you migrate from Nitro v2. |
| 11 | + |
| 12 | +## `nitropack` is renamed to `nitro` |
| 13 | + |
| 14 | +The NPM package [nitropack](https://www.npmjs.com/package/nitropack) (v2) has been renamed to [nitro](https://www.npmjs.com/package/nitro) (v3). |
| 15 | + |
| 16 | +**Migration:** Update the `nitropack` dependency to `nitro` in `package.json`: |
| 17 | + |
| 18 | +> [!NOTE] |
| 19 | +> Currently, only nightly releases are available. |
| 20 | +
|
| 21 | +```diff |
| 22 | +{ |
| 23 | + "dependencies": { |
| 24 | +-- "nitropack": "latest" |
| 25 | +++ "nitro": "npm:nitro-nightly@latest" |
| 26 | + } |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +**Migration:** Search your codebase and rename all instances of nitropack to nitro: |
| 31 | + |
| 32 | +```diff |
| 33 | +-- import { defineNitroConfig } from "nitropack/config" |
| 34 | +++ import { defineNitroConfig } from "nitro/config" |
| 35 | +``` |
| 36 | + |
| 37 | +## nitro/runtime/* |
| 38 | + |
| 39 | +Previously, you could import from both `nitro/runtime` and `nitro/runtime/*`. |
| 40 | + |
| 41 | +Support for nested paths has been removed to prevent exposing Nitro internals. |
| 42 | + |
| 43 | +**Migration:** Search for nitro/runtime/ imports and replace them with nitro/runtime: |
| 44 | + |
| 45 | +```diff |
| 46 | +-- import { useStorage } from "nitropack/runtime/storage" |
| 47 | +++ import { useStorage } from "nitro/runtime" |
| 48 | +``` |
| 49 | + |
| 50 | +## Minimum Supported Node.js Version: 20 |
| 51 | + |
| 52 | +Nitro now requires a minimum Node.js version of 20, as Node.js 18 reaches end-of-life in [April 2025](https://nodejs.org/en/about/previous-releases). |
| 53 | + |
| 54 | +Please upgrade to the [latest LTS](https://nodejs.org/en/download) version (>= 20). |
| 55 | + |
| 56 | +**Migration:** |
| 57 | + |
| 58 | +- Check your local Node.js version using `node --version` and update if necessary. |
| 59 | +- If you use a CI/CD system for deployment, ensure that your pipeline is running Node.js 20 or higher. |
| 60 | +- If your hosting provider manages the Node.js runtime, make sure it’s set to version 20, 22, or later. |
| 61 | + |
| 62 | +## Type Imports |
| 63 | + |
| 64 | +Nitro types are now only exported from `nitro/types`. |
| 65 | + |
| 66 | +**Migration:** Import types from nitro/types instead of nitro: |
| 67 | + |
| 68 | +```diff |
| 69 | +-- import { NitroRuntimeConfig } from "nitropack" |
| 70 | +++ import { NitroRuntimeConfig } from "nitro/types" |
| 71 | +``` |
| 72 | + |
| 73 | +## App Config Support Removed |
| 74 | + |
| 75 | +Nitro v2 supported a bundled app config that allowed defining configurations in `app.config.ts` and accessing them at runtime via `useAppConfig()`. |
| 76 | + |
| 77 | +This feature had been removed. |
| 78 | + |
| 79 | +**Migration:** |
| 80 | + |
| 81 | +Use a regular `.ts` file in your server directory and import it directly. |
| 82 | + |
| 83 | +## Removed Subpath Exports |
| 84 | + |
| 85 | +Nitro v2 introduced multiple subpath exports, some of which have been removed: |
| 86 | + |
| 87 | +- `nitropack/core` (use `nitro`) |
| 88 | +- `nitropack/runtime/*` |
| 89 | +- `nitropack/dist/runtime/*` |
| 90 | +- `nitropack/presets/*` |
| 91 | +- `nitro/rollup` |
| 92 | +- `nitropack/kit` |
| 93 | + |
| 94 | +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. |
| 95 | + |
| 96 | +**Migration:** |
| 97 | + |
| 98 | +- Use `NitroModule` from `nitro/types` instead of `defineNitroModule` from the kit. |
| 99 | +- Prefer built-in Nitro presets (external presets are only for evaluation purposes). |
0 commit comments