From 1c8b751cfadbbc2dd6a89fc1c59ed755ed5b9bb5 Mon Sep 17 00:00:00 2001
From: pooya parsa <pyapar@gmail.com>
Date: Mon, 15 Nov 2021 21:41:05 +0100
Subject: [PATCH] docs: improve `useState` with shared composable (#1945)

---
 docs/content/3.docs/1.usage/2.state.md      | 62 ++++++++++++++-------
 examples/use-state/app.vue                  |  4 +-
 examples/use-state/composables/states.ts    |  1 +
 examples/use-state/plugins/locale.server.ts |  8 +--
 4 files changed, 50 insertions(+), 25 deletions(-)
 create mode 100644 examples/use-state/composables/states.ts

diff --git a/docs/content/3.docs/1.usage/2.state.md b/docs/content/3.docs/1.usage/2.state.md
index 378cfe7696..6a21ab774b 100644
--- a/docs/content/3.docs/1.usage/2.state.md
+++ b/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
-useState<T>(key: string, init?: () => T): Ref<T>
+Using [auto imported composables](/docs/directory-structure/composables) we can define global typesafe states.
+
+```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
-* **init**: a function that provides initial value for the state when it's not initiated
+```vue [app.vue]
+<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]
-import { defineNuxtPlugin, useState } from '#app'
+```ts [composables/states.ts]
+export const useLocale = () => useState<string>('locale', () => 'en')
+```
 
-export default defineNuxtPlugin((nuxt) => {
-  const locale = useState(
-    'locale',
-    () => nuxt.ssrContext.req.headers['accept-language']?.split(',')[0]
-  )
+```ts [plugins/locale.server.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  const locale = useLocale()
+  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>
diff --git a/examples/use-state/app.vue b/examples/use-state/app.vue
index 9e088ab06f..fe8b73017d 100644
--- a/examples/use-state/app.vue
+++ b/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>
diff --git a/examples/use-state/composables/states.ts b/examples/use-state/composables/states.ts
new file mode 100644
index 0000000000..b142eba6e9
--- /dev/null
+++ b/examples/use-state/composables/states.ts
@@ -0,0 +1 @@
+export const useLocale = () => useState<string>('locale')
diff --git a/examples/use-state/plugins/locale.server.ts b/examples/use-state/plugins/locale.server.ts
index 52ed70d8b6..e206f486cc 100644
--- a/examples/use-state/plugins/locale.server.ts
+++ b/examples/use-state/plugins/locale.server.ts
@@ -1,6 +1,4 @@
-import { useState } from '#app'
-
-export default defineNuxtPlugin((nuxt) => {
-  const locale = useState('locale')
-  locale.value = nuxt.ssrContext.req.headers['accept-language']?.split(',')[0]
+export default defineNuxtPlugin((nuxtApp) => {
+  const locale = useLocale()
+  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
 })