docs: many improvements

posva · posva · commit 2725596921b8 · 2023-07-13T11:48:34.000+02:00
diff --git a/docs/cookbook/migration-v2-v3.md b/docs/cookbook/migration-v2-v3.md
@@ -17,17 +17,17 @@ Terms starting with _rtdb_ are now prefixed with _database_ to match the Firebas
 
 The `firestorePlugin` and `rtdbPlugin` are now deprecated in favor of _modules_. They are still available but will be removed in the next major version. You should use `VueFire`, `VueFireFirestoreOptionsAPI` and `VueFireDatabaseOptionsAPI` instead:
 
-```diff
+```ts
  const app = createApp({})
 
  // for firestore
--app.use(firestorePlugin)
-+app.use(VueFire, { modules: [VueFireFirestoreOptionsAPI] })
+app.use(firestorePlugin, options) // [!code --]
+app.use(VueFire, { modules: [VueFireFirestoreOptionsAPI(options)] }) // [!code ++]
 
  // for database
--app.use(rtdbPlugin)
-+app.use(VueFire, { modules: [VueFireDatabaseOptionsAPI] })
-````
+app.use(rtdbPlugin, options) // [!code --]
+app.use(VueFire, { modules: [VueFireDatabaseOptionsAPI(options)] }) // [!code ++]
+```
 
 ## Breaking changes
 
diff --git a/docs/cookbook/subscriptions-external.md b/docs/cookbook/subscriptions-external.md
@@ -23,4 +23,4 @@ export const useTodoStore = defineStore('todos', () => {
 })
 ```
 
-Note you will still have to follow the [Firebase API](https://firebase.google.com/docs/firestore/manage-data/structure-data) (e.g. `addDoc()`, `updateDoc()`, etc) to update the data.
+Note you will still have to follow the [Firebase API](https://firebase.google.com/docs/firestore/manage-data/structure-data) (e.g. `addDoc()`, `updateDoc()`, etc) to update the data and you will also need [to wait for the data to be loaded on the server](../guide/ssr.md#usage-outside-of-components).
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -6,12 +6,22 @@ Before using VueFire, make sure you have a Firebase account and a project setup
 
 In order to get started make sure to install the latest version of `vuefire` as well as `firebase`:
 
-```sh
+::: code-group
+
+```sh [pnpm]
+pnpm i vuefire firebase
+```
+
+```sh [yarn]
 yarn add vuefire firebase
-# or
-npm install vuefire firebase
 ```
 
+```sh [npm]
+npm i vuefire firebase
+```
+
+:::
+
 ::: warning
 
 VueFire requires Firebase JS SDK >= 9 but **is compatible with Vue 2 and Vue 3**.
@@ -71,7 +81,7 @@ Note that we will refer to `database` and `firestore` as `db` in examples where
 
 First, install the VueFire Vue plugin. It will allow you to add extra modules like [AppCheck](./app-check.md) or [Auth](./auth.md) to your app.
 
-```ts
+```ts{2,8-15}
 import { createApp } from 'vue'
 import { VueFire, VueFireAuth } from 'vuefire'
 import App from './App.vue'
@@ -93,10 +103,9 @@ app.mount('#app')
 
 This will give you access to some [convenient composables](./firebase-composables.md) like `useFirebaseApp()`, `useFirestore()` and `useDatabase()` in your components:
 
-```vue
+```vue{2-3}
 <script setup>
 import { useFirestore } from 'vuefire'
-
 const db = useFirestore()
 </script>
 
@@ -216,27 +225,29 @@ VueFire can also be used with the Options API, while less flexible, it's still a
 
 <FirebaseExample>
 
-```js
+```js{2,7-10}
 import { createApp } from 'vue'
 import { VueFire, VueFireDatabaseOptionsAPI } from 'vuefire'
 
 const app = createApp(App)
 app.use(VueFire, {
   // ...
   modules: [
+    // Add any modules you want to use here
     VueFireDatabaseOptionsAPI(),
   ],
 })
 ```
 
-```js
+```js{2,7-10}
 import { createApp } from 'vue'
 import { VueFire, VueFireFirestoreOptionsAPI } from 'vuefire'
 
 const app = createApp(App)
 app.use(VueFire, {
   // ...
   modules: [
+    // Add any modules you want to use here
     VueFireFirestoreOptionsAPI(),
   ],
 })
diff --git a/docs/guide/realtime-data.md b/docs/guide/realtime-data.md
@@ -26,7 +26,7 @@ const someTodo = useDatabaseObject(dbRef(db, 'todos', 'someId'))
 <template>
   <ul>
     <li v-for="todo in todos" :key="todo.id">
-     <span>{{ todo.text }}</span>
+      <span>{{ todo.text }}</span>
     </li>
   </ul>
 </template>
@@ -44,7 +44,7 @@ const someTodo = useDocument(doc(collection(db, 'todos'), 'someId'))
 <template>
   <ul>
     <li v-for="todo in todos" :key="todo.id">
-     <span>{{ todo.text }}</span>
+      <span>{{ todo.text }}</span>
     </li>
   </ul>
 </template>
@@ -61,18 +61,16 @@ Sometimes, you need to start observing a different document or collection, let's
 ```ts
 const route = useRoute()
 // since route is reactive, `contactSource` will be reactive too
-const contactSource = computed(
-  () => dbRef(db, 'contacts/' + route.params.id)
-)
+const contactSource = computed(() => dbRef(db, 'contacts/' + route.params.id))
 // contact will always be in sync with the data source
 const contact = useDatabaseObject(contactSource)
 ```
 
 ```ts
 const route = useRoute()
 // since route is reactive, `contactSource` will be reactive too
-const contactSource = computed(
-  () => doc(collection(db, 'contacts'), route.params.id)
+const contactSource = computed(() =>
+  doc(collection(db, 'contacts'), route.params.id)
 )
 // contact will always be in sync with the data source
 const contact = useDocument(contactSource)
@@ -102,7 +100,7 @@ const {
   // did the subscription fail?
   error,
   // A promise that resolves or rejects when the initial state is loaded
-  promise
+  promise,
 } = useDocument(contactSource)
 ```
 
@@ -118,20 +116,28 @@ To fetch data only _once_, pass the [`once`](https://vuefire.vuejs.org/api/inter
 
 <FirebaseExample>
 
-```ts{3,4}
+```ts{5,8}
 import { useDatabaseList, useDatabaseObject } from 'vuefire'
 import { ref as dbRef } from 'firebase/database'
 
-const todos = useDatabaseList(dbRef(db, 'todos'), { once: true })
-const someTodo = useDatabaseObject(dbRef(db, 'todos', 'someId'), { once: true })
+const todos = useDatabaseList(dbRef(db, 'todos'), {
+  once: true,
+})
+const someTodo = useDatabaseObject(dbRef(db, 'todos', 'someId'), {
+  once: true,
+})
 ```
 
-```ts{3,4}
+```ts{5,8}
 import { useCollection, useDocument } from 'vuefire'
 import { collection, doc } from 'firebase/firestore'
 
-const todos = useCollection(collection(db, 'todos'), { once: true })
-const someTodo = useDocument(doc(collection(db, 'todos'), 'someId'), { once: true })
+const todos = useCollection(collection(db, 'todos'), {
+  once: true,
+})
+const someTodo = useDocument(doc(collection(db, 'todos'), 'someId'), {
+  once: true,
+})
 ```
 
 </FirebaseExample>
@@ -239,7 +245,7 @@ Given some _users_ with _documents_ that are being viewed by other _users_. This
 
 ```js
 {
-  name: 'Jessica',
+  name: 'Claire',
   documents: [
     // The document is stored somewhere else. Here we are only holding a reference
     doc(collection(db, 'documents'), 'gift-list'),
@@ -263,22 +269,22 @@ In the example above, `documents` is an array of References. Let's look at the d
 
 ```js
 {
-  name: 'Jessica',
+  name: 'Claire',
   documents: [
     {
       content: '...',
       sharedWith: [
         {
-          name: 'Alex',
+          name: 'Chris',
           documents: [
-            'documents/alex-todo-list',
+            'documents/chris-todo-list',
           ]
         },
         {
-          name: 'Robin',
+          name: 'Leon',
           documents: [
-            'documents/robin-todo-list',
-            'documents/robin-book',
+            'documents/leon-todo-list',
+            'documents/leon-book',
           ],
         },
       ],
@@ -287,7 +293,7 @@ In the example above, `documents` is an array of References. Let's look at the d
 }
 ```
 
-`documents.sharedWith.documents` end up as arrays of strings. Those strings are actually _paths_ that can be passed to `doc()` as in `doc(db, 'documents/robin-book')` to get the actual reference to the document. By being a string instead of a Reference, it is possible to display a bound document with VueFire as plain text.
+`documents.sharedWith.documents` end up as arrays of strings. Those strings are actually _paths_ that can be passed to `doc()` as in `doc(db, 'documents/leon-book')` to get the actual reference to the document. By being a string instead of a Reference, it is possible to display a bound document with VueFire as plain text.
 
 It is possible to customize this behavior by providing a [`maxRefDepth` option](../api/interfaces/UseDocumentOptions.md#maxrefdepth):
 
@@ -367,3 +373,16 @@ const todoList = useDocument(
   })
 )
 ```
+
+In Firebase 10, `withConverter()` takes two generics instead of one:
+
+```ts{2,5}
+// ...
+import type { DocumentData } from 'firebase/firestore'
+
+const todoList = useDocument(
+  doc(db, 'todos').withConverter<TodoI, DocumentData>({
+    // ...
+  })
+)
+```
diff --git a/docs/guide/ssr.md b/docs/guide/ssr.md
@@ -75,7 +75,8 @@ Note that by default, vite-ssg (used by Vitesse) uses `JSON.stringify()` to seri
 
 ```ts
 // src/main.ts
-import devalue from '@nuxt/devalue'
+// https://github.com/Rich-Harris/devalue#usage
+import devalue from 'devalue'
 import { ViteSSG } from 'vite-ssg'
 import App from './App.vue'
 
@@ -87,7 +88,7 @@ export const createApp = ViteSSG(
   },
   {
     transformState(state) {
-      return import.meta.env.SSR ? devalue(state) : state
+      return import.meta.env.SSR ? devalue.stringify(state) : devalue.parse(state)
     },
   },
 )
@@ -153,14 +154,16 @@ await usePendingPromises()
 
 ## Exclude from hydration
 
-You can exclude data from hydration by passing `false` to the `ssrKey` option:
+You can exclude data from hydration by passing `false` to the `ssrKey` option. This is useful when there is no point in waiting for the data to be fetched on the server, e.g. when the data is not being rendered on the server.
 
 ```ts
 useDocument(..., { ssrKey: false })
 useDatabaseList(..., { ssrKey: false })
 // etc
 ```
 
+This only works if you avoid rendering on server these documents or collections. **If still render them on server, you will get a hydration error on client**.
+
 <!-- TODO: I wonder if we could attach effect scopes to applications so `onServerPrefetch()` is still awaited when attached -->
 
 <!-- 
diff --git a/docs/nuxt/deployment.md b/docs/nuxt/deployment.md
@@ -20,16 +20,18 @@ defineNuxtConfig({
 
 The Spark plan is a free plan that enable most of firebase functions. With this plan, you want to **prerender your app and deploy it as a static site**. In order to do this, make sure **not to apply the Firebase preset** when bundling your app and to use the `generate` command:
 
-```bash
+```sh
 nuxt generate
 ```
 
 You can then let your CI deploy your app to Firebase or do it manually:
 
-```bash
+```sh
 firebase deploy
 ```
 
+Make sure you **don't have** a `nitro.preset` option set in your `nuxt.config.ts` file.
+
 ## Blaze plan
 
 ::: warning
@@ -38,6 +40,10 @@ The Firebase preset is still experimental. It is not recommended to use it in pr
 
 The Blaze plan is a pay-as-you-go that allows you to run Firebase Functions. It's free up to a certain amount of requests. With this plan, you can either do the same as with the [Spark plan](#spark-plan) (cheaper) or build with the Firebase preset and deploy your app as a serverless function:
 
-```bash
+```sh
 NITRO_PRESET=firebase nuxt build
 ```
+
+### Route Rules
+
+On top of prerendering any routes, you can also use [the `routeRules` option](https://nuxt.com/docs/api/configuration/nuxt-config#routerules-1) to apply any headers like cache options, redirects or even static rendering.
diff --git a/docs/nuxt/getting-started.md b/docs/nuxt/getting-started.md
@@ -6,16 +6,40 @@ The Nuxt VueFire module is still a work in progress and it might contain breakin
 
 ## Installation
 
-```bash
+::: code-group
+
+```sh [pnpm]
+pnpm install vuefire nuxt-vuefire firebase
+```
+
+```sh [yarn]
+yarn add vuefire nuxt-vuefire firebase
+```
+
+```sh [npm]
 npm install vuefire nuxt-vuefire firebase
 ```
 
+:::
+
 Additionally, if you are using [SSR](https://nuxt.com/docs/api/configuration/nuxt-config/#ssr), you need to install `firebase-admin` and its peer dependencies:
 
-```bash
-npm install firebase-admin @firebase/app-types
+::: code-group
+
+```sh [pnpm]
+pnpm install firebase-admin firebase-functions @firebase/app-types
+```
+
+```sh [yarn]
+yarn add firebase-admin firebase-functions @firebase/app-types
+```
+
+```sh [npm]
+npm install firebase-admin firebase-functions @firebase/app-types
 ```
 
+:::
+
 ## Configuration
 
 Next, add `nuxt-vuefire` to the `modules` section of `nuxt.config.js` and configure it with the credentials created in your app settings in your project overview (`https://console.firebase.google.com/project/YOUR_PROJECT_NAME/overview)`. You can find more details [in Firebase Documentation](https://firebase.google.com/docs/web/setup#create-project). It should look something like this:
@@ -39,6 +63,8 @@ export default defineNuxtConfig({
 })
 ```
 
+### Configuring the Admin SDK
+
 If you are using SSR with any auth related feature, you will need to create a [service account](https://firebase.google.com/support/guides/service-accounts) and provide its content as an _environment variable_ named `GOOGLE_APPLICATION_CREDENTIALS`.
 
 In local development it's more convenient to put the `service-account.json` file alongside other files and refer to its path in the environment variable:
@@ -48,7 +74,12 @@ GOOGLE_APPLICATION_CREDENTIALS=service-account.json
 ```
 
 :::tip
-This service account file contains sensitive information and should **not be committed to your repository**.
+This service account file contains sensitive information and should **not be committed to your repository**. Make sure to exclude it from your version control system:
+
+```sh
+echo service-account.json >> .gitignore
+```
+
 :::
 
 ### Additional configuration
