docs: improve useState with shared composable (#1945)

docs/content/3.docs/1.usage/2.state.md

@@ -1,44 +1,68 @@
 # State
 
-Nuxt provides `useState` to create a globally shared state.
+Nuxt provides `useState` to create a globally shared state within the context.
 
-## `useState`
+`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.
 
-Within your pages, components and plugins you can use `useState`. It can be used to create your own store implementation.
+::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!
 
-You can think of it as an SSR-friendly ref in that its value will be hydrated (preserved) after server-side rendering. It is shared across all components.
+✅ 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>
+```
+
+* **key**: A unique key ensuring that data fetching can be properly de-duplicated across requests
+* **init**: A function that provides initial value for the state when it's not initiated
+* **T**: (typescript only) Specify type of state
 
 ::alert{icon=👉}
 **`useState` only works during `setup` or `Lifecycle Hooks`**
 ::
 
-### Usage
+## Shared State
 
-```js
+Using [auto imported composables](/docs/directory-structure/composables) we can define global typesafe states.
-useState<T>(key: string, init?: () => T): Ref<T>
+
+```ts [composables/states.ts]
+export const useColor = () => useState<string>('color', () => 'pink')
 ```
 
-* **key**: a unique key ensuring that data fetching can be properly de-duplicated across requests
+```vue [app.vue]
-* **init**: a function that provides initial value for the state when it's not initiated
+<script setup>
+const color = useColor() // Same as useState('color')
+</script>
 
-### Example
+<template>
+  Current color: {{ color }}
+</template>
+```
+
+## Example
 
 In this example, we use a server-only plugin to find about request locale.
 
-```ts [plugins/locale.server.ts]
+```ts [composables/states.ts]
-import { defineNuxtPlugin, useState } from '#app'
+export const useLocale = () => useState<string>('locale', () => 'en')
+```
 
-export default defineNuxtPlugin((nuxt) => {
+```ts [plugins/locale.server.ts]
-  const locale = useState(
+export default defineNuxtPlugin((nuxtApp) => {
-    'locale',
+  const locale = useLocale()
-    () => nuxt.ssrContext.req.headers['accept-language']?.split(',')[0]
+  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
-  )
 })
 ```
 
-```vue
+```vue [app.vue]
 <script setup>
-const locale = useState('locale')
+const locale = useLocale() // Same as useState('locale')
 </script>
 
 <template>

examples/use-state/app.vue

@@ -8,6 +8,8 @@
 </template>
 
 <script setup>
-const locale = useState('locale')
+// Defined in composables/stats.ts
+// same as useState('locale')
+const locale = useLocale()
 const updateLocale = () => { locale.value = 'tlh-klingon' }
 </script>

examples/use-state/composables/states.ts

@@ -0,0 +1 @@
+export const useLocale = () => useState<string>('locale')

examples/use-state/plugins/locale.server.ts

@@ -1,6 +1,4 @@
-import { useState } from '#app'
+export default defineNuxtPlugin((nuxtApp) => {
-
+  const locale = useLocale()
-export default defineNuxtPlugin((nuxt) => {
+  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
-  const locale = useState('locale')
-  locale.value = nuxt.ssrContext.req.headers['accept-language']?.split(',')[0]
 })