docs: new migration page

diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts
index c74153bd7f55289b318155e2a2ec102de3549dbc..0cb3dfb68332ca09ef5a510caf6cb025943d00c3 100644 (file)
--- a/packages/docs/.vitepress/config/en.ts
+++ b/packages/docs/.vitepress/config/en.ts
@@ -132,6 +132,10 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
               text: 'VSCode Snippets',
               link: '/cookbook/vscode-snippets.html',
             },
+            {
+              text: 'Migration from v2 to v3',
+              link: '/cookbook/migration-v2-v3.html',
+            },
             {
               text: 'Migration from v0/v1 to v2',
               link: '/cookbook/migration-v1-v2.html',

diff --git a/packages/docs/cookbook/migration-v2-v3.md b/packages/docs/cookbook/migration-v2-v3.md
new file mode 100644 (file)
index 0000000..448855f
--- /dev/null
+++ b/packages/docs/cookbook/migration-v2-v3.md
@@ -0,0 +1,31 @@
+# Migrating from v2 to v3
+
+Pinia v3 is a _boring_ major release with no new features. It drops deprecated APIs and updates major dependencies. It only supports Vue 3. If you are using Vue 2, you can keep using v2. You can probably just update Pinia's version but this guide is here to help you in case you encounter any issues.
+
+## Deprecations
+
+### `defineStore({ id })`
+
+The `defineStore()` signature that accepts an object with an `id` property is deprecated. You should use the `id` parameter instead:
+
+```ts
+defineStore({ // [!code --]
+  id: 'storeName', // [!code --]
+defineStore('storeName', { // [!code ++]
+  // ...
+})
+```
+
+### `PiniaStorePlugin`
+
+This deprecated type alias has been removed in favor of `PiniaPlugin`.
+
+## New versions
+
+- Only Vue 3 is supported.
+- TypeScript 5 or newer is required.
+- The devtools API has been upgraded to [v7](https://devtools.vuejs.org).
+
+## Nuxt
+
+The Nuxt module has been updated to support Nuxt 3. If you are using Nuxt 2 or Nuxt bridge, you can keep using the old version of Pinia.