Skip to content

Commit 8b05869

Browse files
authored
docs: init migration guide (#3203)
1 parent 14a5e05 commit 8b05869

File tree

3 files changed

+105
-3
lines changed

3 files changed

+105
-3
lines changed

README.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,10 @@
99

1010
Create web servers that run anywhere! 📖 [**documentation**](https://nitro.build)
1111

12-
> [!NOTE]
13-
> You are on the **v3 development branch**. Checkout the [v2](https://github.com/nitrojs/nitro/tree/v2) branch for current stable.
12+
> [!IMPORTANT]
13+
> You are on the **v3 beta branch**. Checkout the [v2](https://github.com/nitrojs/nitro/tree/v2) branch for current stable.
14+
15+
Check [migration guide](./docs/1.guide/00.migration.md) for migrating from Nitro v2 to Nitro v3.
1416

1517
## Contribution
1618

docs/1.guide/0.index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ icon: ph:book-open-duotone
77
> Create web servers with all necessary features and deploy them wherever you prefer.
88
99
> [!IMPORTANT]
10-
> You are currently reading Nitro v3 development docs.
10+
> You are currently reading Nitro v3 beta docs.
11+
> Check the [migration guide](/guide/migration) for migrating from Nitro v2.
1112
1213
## Intro
1314

docs/1.guide/00.migration.md

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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

Comments
 (0)