docs: init migration guide (#3203)

Author: pi0

README.md

@@ -9,8 +9,10 @@
 
 Create web servers that run anywhere! 📖 [**documentation**](https://nitro.build)
 
-> [!NOTE]
-> You are on the **v3 development branch**. Checkout the [v2](https://github.com/nitrojs/nitro/tree/v2) branch for current stable.
+> [!IMPORTANT]
+> You are on the **v3 beta branch**. Checkout the [v2](https://github.com/nitrojs/nitro/tree/v2) branch for current stable.
+
+Check [migration guide](./docs/1.guide/00.migration.md) for migrating from Nitro v2 to Nitro v3.
 
 ## Contribution
 

docs/1.guide/0.index.md

@@ -7,7 +7,8 @@ icon: ph:book-open-duotone
 > Create web servers with all necessary features and deploy them wherever you prefer.
 
 > [!IMPORTANT]
-> You are currently reading Nitro v3 development docs.
+> You are currently reading Nitro v3 beta docs.
+> Check the [migration guide](/guide/migration) for migrating from Nitro v2.
 
 ## Intro
 

docs/1.guide/00.migration.md

@@ -0,0 +1,99 @@
+---
+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](https://www.npmjs.com/package/nitropack) (v2) has been renamed to [nitro](https://www.npmjs.com/package/nitro) (v3).
+
+**Migration:** Update the `nitropack` dependency to `nitro` in `package.json`:
+
+> [!NOTE]
+> Currently, only nightly releases are available.
+
+```diff
+{
+  "dependencies": {
+--    "nitropack": "latest"
+++    "nitro": "npm:nitro-nightly@latest"
+  }
+}
+```
+
+**Migration:** Search your codebase and rename all instances of nitropack to nitro:
+
+```diff
+-- 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:
+
+```diff
+-- 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](https://nodejs.org/en/about/previous-releases).
+
+Please upgrade to the [latest LTS](https://nodejs.org/en/download) 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:
+
+```diff
+-- 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.
+
+## 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).