docs: refactors

Author: posva

docs/.vitepress/config.ts

@@ -152,6 +152,14 @@ export default defineConfig({
               text: 'Cookbook',
               link: '/cookbook/',
             },
+            {
+              text: 'Migration from VueFire 2',
+              link: '/cookbook/migration-v2-v3',
+            },
+            {
+              text: 'Binding to existing refs',
+              link: '/cookbook/subscriptions-external',
+            },
           ],
         },
       ],

docs/guide/subscriptions-external.md renamed to docs/cookbook/subscriptions-external.md

@@ -0,0 +1,25 @@
+# Usage with Vuex
+
+Vuex is supported but due to its nature with mutations, it's a bit more verbose to use than Pinia. It's recommended to use Pinia instead of Vuex if you can, your DX will also improve.
+
+You must set the `strict` option to `false` in order to use Vuex with VueFire.
+
+You can can call `useCollection()` and other composables from VueFire within your components to connect to your store:
+
+```ts
+import { doc } from 'firebase/firestore'
+import { toRef } from 'vue'
+import { useStore } from 'vuex'
+import { useDocument } from 'vuefire'
+
+const store = useStore()
+const userDataRef = doc(firestore, 'users', userId)
+
+const user = toRef(store.state, 'user')
+
+useDocument(userDataRef, { target: user })
+```
+
+In this scenario, the Firebase subscription will stop when the component is unmounted. In order to keep the subscription alive after the component gets unmounted, use an `effectScope()` within an action:
+
+<!-- TODO: I think we can find a simpler way -->

docs/cookbook/vuex.md

@@ -2,7 +2,7 @@
 
 In VueFire, subscriptions to data changes are handled transparently. That's why we always talk about _binding_: you only provide the _data source_ (Collection, Query or Document), and VueFire takes care of the rest!
 
-When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase. It exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](./subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](#options-api), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
+When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase. It exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](../cookbook/subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](#options-api), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
 
 ## Declarative realtime data