From 07ba36d721c353ad86e4b7c6b72280e6f84fdf58 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= <seb@nuxtjs.com>
Date: Tue, 16 Nov 2021 17:12:36 +0100
Subject: [PATCH] docs: useState improvements (#1973)

---
 docs/content/3.docs/1.usage/2.state.md | 39 +++++++++++++-------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/docs/content/3.docs/1.usage/2.state.md b/docs/content/3.docs/1.usage/2.state.md
index 4a465bf87b..04f86530df 100644
--- a/docs/content/3.docs/1.usage/2.state.md
+++ b/docs/content/3.docs/1.usage/2.state.md
@@ -1,22 +1,13 @@
 # State
 
-Nuxt provides `useState` to create a globally shared state within the context.
+Nuxt provides `useState` composable to create a reactive and ssr-friendly shared state across components.
 
-`useState` is SSR-friendly `ref` replacement in that its value will be hydrated (preserved) after server-side rendering and is shared across all components using a unique key.
+`useState` is a SSR-friendly [`ref`](https://v3.vuejs.org/api/refs-api.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.
 
-::alert{icon=⚠️}
-Never define `const state = ref()` outside of `<script setup>` or `setup()` function.
-Such state will be shared across all users visiting your website and can lead to memory leaks!
+## Signature
 
-✅ Instead use `const useX = () => useState('x')`
-::
-
-## Usage
-
-Within your pages, components and plugins you can use `useState`.
-
-```js
-const state = useState<T>(key: string, init?: () => T): Ref<T>
+```ts
+useState<T>(key: string, init?: () => T): Ref<T>
 ```
 
 * **key**: A unique key ensuring that data fetching can be properly de-duplicated across requests
@@ -24,7 +15,17 @@ const state = useState<T>(key: string, init?: () => T): Ref<T>
 * **T**: (typescript only) Specify type of state
 
 ::alert{icon=👉}
-**`useState` only works during `setup` or `Lifecycle Hooks`**
+`useState` only works during `setup` or [`Lifecycle Hooks`](https://v3.vuejs.org/guide/composition-api-lifecycle-hooks.html#lifecycle-hooks).
+::
+
+## Best practices
+
+::alert{type=danger icon=🚨}
+Never define `const state = ref()` outside of `<script setup>` or `setup()` function.<br>
+Such state will be shared across all users visiting your website and can lead to memory leaks!
+::
+::alert{type=success icon=✅}
+Instead use `const useX = () => useState('x')`
 ::
 
 ## Examples
@@ -53,13 +54,13 @@ const counter = useState('counter', () => Math.round(Math.random() * 1000))
 
 :button-link[Open on StackBlitz]{href="https://stackblitz.com/github/nuxt/framework/tree/main/examples/use-state?terminal=dev" blank}
 
-### Advanced Example
+### Advanced
 
-In this example, we use a composable that detects the user's default locale and keeps it in a `locale` state.
+In this example, we use a composable that detects the user's default locale from the request HTTP headers and keeps in `locale` state.
 
 :button-link[Open on StackBlitz]{href="https://stackblitz.com/github/nuxt/framework/tree/main/examples/locale?terminal=dev" blank}
 
-## Shared State
+## Shared state
 
 By using [auto-imported composables](/docs/directory-structure/composables) we can define global type-safe states and import them across the app.
 
@@ -74,6 +75,6 @@ const color = useColor() // Same as useState('color')
 </script>
 
 <template>
-  Current color: {{ color }}
+  <p>Current color: {{ color }}</p>
 </template>
 ```