docs: global options

Author: posva

docs/.vitepress/config.ts

@@ -155,6 +155,10 @@ export default defineConfig({
             //   text: 'Writing to the database',
             //   link: '/guide/writing-data',
             // },
+            {
+              text: 'Global Options',
+              link: '/guide/global-options',
+            },
           ],
         },
         {

docs/cookbook/migration-v2-v3.md

@@ -94,6 +94,27 @@ The `$rtdbBind` method is now called `$databaseBind` to have a consistent naming
 
 Note that for compatibility reasons, the `$rtdbBind` and `$rtdbUnbind` methods are still available but marked as deprecated.
 
+### Default changes to `reset` and `wait`
+
+The default value of `reset` is now `false` and the default value of `wait` is now `true`. This should be seen as an enhancement as it makes it easier to load new _documents_ or _collections_ without affecting the view while data is being fetched for the first time from Firebase. If you wish the old behavior, you can enforce these settings globally:
+
+```ts
+app.use(VueFire, {
+  modules: [
+    VueFireFirestoreOptionsAPI({
+      // same behavior as vuefire v2
+      reset: true,
+      wait: false,
+    }),
+    VueFireDatabaseOptionsAPI({
+      // same behavior as vuefire v2
+      reset: true,
+      wait: false,
+    }),
+  ]
+})
+```
+
 ## Vuexfire
 
 :::tip

docs/guide/global-options.md

@@ -1,11 +1,21 @@
-# Global Options
+# Firestore and Database global Options
 
-You can modify the behavior of VueFire by modifying the global options:
+If you find yourself passing around the same options to `useDocument()`, `useObject()`, ..., you can use the global options to avoid repeating yourself:
 
-TODO:
+<FirestoreExample>
 
 ```ts
-import { globalFirestoreOptionss } from 'vuefire'
+import { globalDatabaseOptions } from 'vuefire'
+
+globalDatabaseOptions.serialize = ...
+```
+
+```ts
+import { globalFirestoreOptions } from 'vuefire'
 
 globalFirestoreOptions.converter = ...
 ```
+
+</FirestoreExample>
+
+Changing these options will affect all calls to `useDocument()`, `useObject()`, ... in your application **and the Options API usage** as well (`$firestoreBind()`, `$rtdbBind()`).

docs/guide/options-api-realtime-data.md

@@ -28,6 +28,25 @@ app.use(VueFire, {
 })
 ```
 
+You can pass global options to the modules but note **these options are limited to the Options API usage**.They do not affect composition API calls such as `useDocument()` and `useObject()`. [Check the global options](./global-options.md) to see how you can override those.
+
+```ts
+app.use(VueFire, {
+  modules: [
+    VueFireFirestoreOptionsAPI({
+      // same behavior as vuefire v2
+      reset: true,
+      wait: false,
+    }),
+    VueFireDatabaseOptionsAPI({
+      // same behavior as vuefire v2
+      reset: true,
+      wait: false,
+    }),
+  ]
+})
+```
+
 ## Declarative binding
 
 Any Database Reference provided in a `firebase`/`firestore` option will be bound at creation (after Vue's `beforeMount` hook) to the specified key on the component. In the following example we bind a Collection of Documents to our `documents` property. The key provided in the `firebase`/`firestore` option (`documents`) must be initialized in the `data` of the component: