docs: third-party state management and migration guide (#19798)

docs/1.getting-started/7.state-management.md

@@ -1,11 +1,11 @@
 ---
 navigation.icon: uil:database
-description: Nuxt provides useState composable to create a reactive and SSR-friendly shared state.
+description: Nuxt provides powerful state management libraries and the useState composable to create a reactive and SSR-friendly shared state.
 ---
 
 # State Management
 
-Nuxt provides useState composable to create a reactive and SSR-friendly shared state across components.
+Nuxt provides the `useState` composable to create a reactive and SSR-friendly shared state across components.
 
 `useState` is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core.html#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
 
@@ -84,3 +84,13 @@ const color = useColor() // Same as useState('color')
   <p>Current color: {{ color }}</p>
 </template>
 ```
+
+## Using third-party libraries
+
+Nuxt **used to rely** on the Vuex library to provide global state management. If you are migrating from Nuxt 2, please head to [the migration guide](/docs/migration/configuration#vuex).
+
+Nuxt is not opiniated about state management, so feel free to choose the right solution for your needs. There are multiple integrations with the most popular state management libraries, including:
+
+- [Pinia](/modules/pinia) - the official Vue recommendation
+- [Harlem](/modules/harlem) - immutable global state management
+- [XState](/modules/xstate) - state machine approach with tools for visualising and testing your state logic

docs/7.migration/2.configuration.md

@@ -135,4 +135,54 @@ It is not currently possible to use the Vue 3 migration build with Nuxt 3 RC.
 
 Nuxt no longer provides a Vuex integration. Instead, the official Vue recommendation is to use `pinia`, which has built-in Nuxt support via a [Nuxt module](https://pinia.vuejs.org/ssr/nuxt.html). [Find out more about pinia here](https://pinia.vuejs.org/).
 
+A simple way to provide global state management with pinia would be:
+
+Install the [@nuxt/pinia](https://nuxt.com/modules/pinia) module:
+
+```bash
+yarn add pinia @pinia/nuxt
+```
+
+Create a `store` folder at the root of your application:
+
+```ts [store/index.ts]
+import { defineStore } from 'pinia'
+
+export const useMainStore = defineStore('main', {
+  state: () => ({
+    counter: 0,
+  }),
+  actions: {
+    increment() {
+      // `this` is the store instance
+      this.counter++
+    },
+  },
+})
+```
+
+Create a [plugin](/docs/guide/directory-structure/plugins) file to globalize your store:
+
+```ts [plugins/pinia.ts]
+import { useMainStore } from '~/store'
+
+export default defineNuxtPlugin(({ $pinia }) => {
+  return {
+    provide: {
+      store: useMainStore($pinia)
+    }
+  }
+})
+```
+
 If you want to keep using Vuex, you can manually migrate to Vuex 4 following [these steps](https://vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html).
+
+Once it's done you will need to add the following plugin to your Nuxt app:
+
+```ts [plugins/vuex.ts]
+import store from '~/store'
+
+export default defineNuxtPlugin(nuxtApp => {
+  nuxtApp.vueApp.use(store);
+})
+```