docs: auth signin

Author: posva

Diff for: docs/guide/auth.md

@@ -30,6 +30,83 @@ const auth = useFirebaseAuth()
 </script>
 ```
 
+This is necessary if you want to use the [Firebase Auth API](https://firebase.google.com/docs/auth/web/start#sign_in_existing_users) to sign in users, create users, etc:
+
+```vue{7,9,14,22}
+<script setup>
+import {
+  getRedirectResult,
+  signInWithRedirect,
+  signOut,
+} from 'firebase/auth'
+import { useCurrentUser, useFirebaseAuth } from 'vuefire'
+
+const auth = useFirebaseAuth()! // only exists on client side
+
+// display errors if any
+const error = ref<Error | null>(null)
+function signinRedirect() {
+  signInWithRedirect(auth, someAuthProvider).catch((reason) => {
+    console.error('Failed signinRedirect', reason)
+    error.value = reason
+  })
+}
+
+// only on client side
+onMounted(() => {
+  getRedirectResult(auth).catch((reason) => {
+    console.error('Failed redirect result', reason)
+    error.value = reason
+  })
+})
+</script>
+
+<template>
+  <main>
+    <ErrorBox v-if="error" :error="error" />
+    <button @click="signinRedirect()">SignIn with Google</button>
+  </main>
+</template>
+```
+
+::: tip
+`useFirebaseAuth()` is `null` on the server side, so if you are using TypeScript, you might need to add a `!` to assert that it's not null:
+
+```ts
+const auth = useFirebaseAuth()!
+```
+
+:::
+
+### Providers
+
+There are multiple ways to add the auth providers to your app like exporting a `new GoogleAuthProvider()` instance from the file where we initialize Firebase. Another way is to create it directly in the component where you need it. make sure to add it into a regular `<script>` since each `<script setup>` is scoped to a component instance:
+
+```vue{1-4,17}
+<script lang="ts">
+import { GoogleAuthProvider } from 'firebase/auth'
+export const googleAuthProvider = new GoogleAuthProvider()
+</script>
+
+<script setup>
+import {
+  signInWithPopup,
+  signOut,
+} from 'firebase/auth'
+import { useCurrentUser, useFirebaseAuth } from 'vuefire'
+
+//...
+
+function signinPopup() {
+  error.value = null
+  signInWithPopup(auth, googleAuthProvider).catch((reason) => {
+    console.error('Failed sign', reason)
+    error.value = reason
+  })
+}
+</script>
+```
+
 ## Current User
 
 You can get the current user as a reactive variable with the `useCurrentUser()` composable:
@@ -78,19 +155,29 @@ If you are using `getCurrentUser()` in a navigation guard, make sure to add it b
 
 Once the user is loaded, `getCurrentUser()` will immediately resolve the current user.
 
-Sometimes, the Firebase SDK might be able to automatically log in the user with a hidden cookie or local storage. In that case, you can automatically redirect the user to the page they were trying to access before being automatically logged in:
+Sometimes, the Firebase SDK might be able to automatically log in the user with a hidden cookie or local storage. In that case, you can automatically redirect the user to the page they were trying to access before being automatically logged in. You can even redirect them to the login page if they logout:
 
 ```ts
-// within the Page component displayed for the `/login` route
-onMounted(async () => {
-  const currentUser = await getCurrentUser()
-  if (currentUser) {
-    const to =
-      route.query.redirect && typeof route.query.redirect === 'string'
-        ? route.query.redirect
-        : '/'
-
-    router.push(to)
+// App.vue
+const user = useCurrentUser()
+const router = useRouter()
+const route = useRoute()
+
+watch(user, async (currentUser, previousUser) => {
+  // redirect to login if they logout and the current
+  // route is only for authenticated users
+  if (
+    !currentUser &&
+    previousUser &&
+    isCurrentRouteAuthenticated(route)
+  ) {
+    return router.push({ name: 'login' })
+  }
+  // redirect the user if they are logged in but were
+  // rejected because the user wasn't ready yet, logged in
+  // then got back to this page
+  if (currentUser && typeof route.query.redirect === 'string') {
+    return router.push(route.query.redirect)
   }
 })
 ```