docs: add watching the store

diff --git a/docs/core-concepts/state.md b/docs/core-concepts/state.md
index 4dbb55900f16497cfdb0cd21812194d3a3b6e464..c0e9a425c986082c88e5666f349bb5a924bbccce 100644 (file)
--- a/docs/core-concepts/state.md
+++ b/docs/core-concepts/state.md
@@ -29,6 +29,16 @@ const store = useStore()
 store.counter++
 ```
 
+## Resetting the state
+
+You can _reset_ the state to its initial value by calling the `$reset()` method on the store:
+
+```js
+const store = useStore()
+
+store.$reset()
+```
+
 ### Usage with the options API
 
 If you are not using the composition API, and you are using `computed`, `methods`, ..., you can use the `mapState()` helper to map state properties as readonly computed properties:
@@ -119,3 +129,60 @@ You can also replace the whole state of your application by changing the `state`
 ```js
 pinia.state.value = {}
 ```
+
+## Watching the state
+
+You can watch the state, similar to Vuex's [subscribe method](https://vuex.vuejs.org/api/#subscribe) by simply watching it (since it's a reactive source). Keep in mind a watcher is cleared up when the wrapping component is unmounted so you should add the watcher in your App component or outside of it if you want it to run forever.
+
+```js
+watch(
+  pinia.state,
+  (state) => {
+    // persist the whole state to the local storage whenever it changes
+    localStorage.setItem('piniaState', JSON.stringify(state))
+  },
+  { deep: true }
+)
+```
+
+You can also observe a specific store state instead of all of them by passing a function. Here is an example to watch a store with the id `cart`:
+
+```js
+watch(
+  () => pinia.state.value.cart,
+  (cartState) => {
+    // persist the whole state to the local storage whenever it changes
+    localStorage.setItem('cart', JSON.stringify(cartState))
+  },
+  { deep: true }
+)
+```
+
+Note that depending on when you create the watcher, `pinia.state.value.cart` might be `undefined`. You can also watch a store's `$state` property (this will also make typing work):
+
+```ts
+import { defineStore } from 'pinia'
+
+const useCartStore = defineStore({
+  // ...
+})
+
+const cartStore = useCartStore()
+
+// watch the whole state of the cart
+watch(
+  () => cartStore.$state,
+  () => {
+    // do something
+  },
+  { deep: true }
+)
+
+// you can also watch a getter
+watch(
+  () => cartStore.totalAmount,
+  () => {
+    // do something
+  }
+)
+```

diff --git a/docs/introduction.md b/docs/introduction.md
index 1d240d0ca79e73c09d8530b1d0906f9c793d36bc..53969909d97eefd06380b80db6c0e1aee899a15f 100644 (file)
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -135,3 +135,4 @@ Pinia API is very different from Vuex ≤4, namely:
 - No more magic strings to inject, import the functions, call them, enjoy autocompletion!
 - No need to dynamically add stores, they are all dynamic by default and you won't even notice. Note you can still manually use a store to register it whenever you want but because it is automatic you don't need to worry about it.
 - No more nested structuring of _modules_. You can still nest stores implicitly by importing and _using_ a store inside another but Pinia offers a flat structuring by design while still enabling ways of cross composition among stores.
+- No _namespaced modules_. Given the flat architecture of stores, "namespacing" stores is inherent to how they are defined and you could say all stores are namespaced.