docs: Add stub docs

invertase · Dec 23, 2024 · 18304ee · 18304ee
1 parent bb94a9c
commit 18304ee
Show file tree

Hide file tree

Showing 25 changed files with 341 additions and 37 deletions.
diff --git a/docs.json b/docs.json
@@ -25,6 +25,10 @@
         {
           "href": "/",
           "title": "Introduction"
+        },
+        {
+          "href": "/react-query-firebase",
+          "title": "Migration Guide"
         }
       ]
     },
@@ -43,8 +47,49 @@
       "group": "Authentication",
       "pages": [
         {
-          "href": "/react/hooks/auth/useSignInAnonymouslyMutation",
-          "title": "useSignInAnonymouslyMutation"
+          "title": "Getting Started",
+          "href": "/react/auth"
+        },
+        {
+          "group": "Hooks",
+          "pages": [
+            {
+              "title": "useDeleteUserMutation",
+              "href": "/react/auth/hooks/useDeleteUserMutation"
+            },
+            {
+              "title": "useReloadMutation",
+              "href": "/react/auth/hooks/useReloadMutation"
+            },
+            {
+              "title": "useSendSignInLinkToEmailMutation",
+              "href": "/react/auth/hooks/useSendSignInLinkToEmailMutation"
+            },
+            {
+              "title": "useSignInAnonymouslyMutation",
+              "href": "/react/auth/hooks/useSignInAnonymouslyMutation"
+            },
+            {
+              "title": "useSignInWithCredentialMutation",
+              "href": "/react/auth/hooks/useSignInWithCredentialMutation"
+            },
+            {
+              "title": "useSignInWithEmailAndPasswordMutation",
+              "href": "/react/auth/hooks/useSignInWithEmailAndPasswordMutation"
+            },
+            {
+              "title": "useSignOutMutation",
+              "href": "/react/auth/hooks/useSignOutMutation"
+            },
+            {
+              "title": "useUpdateCurrentUserMutation",
+              "href": "/react/auth/hooks/useUpdateCurrentUserMutation"
+            },
+            {
+              "title": "useVerifyPasswordResetCodeMutation",
+              "href": "/react/auth/hooks/useVerifyPasswordResetCodeMutation"
+            }
+          ]
         }
       ]
     },
@@ -88,40 +133,49 @@
       "group": "Firestore",
       "pages": [
         {
-          "href": "/react/hooks/firestore/useClearIndexedDbPersistenceMutation",
-          "title": "useClearIndexedDbPersistenceMutation"
-        },
-        {
-          "href": "/react/hooks/firestore/useCollectionQuery",
-          "title": "useCollectionQuery"
-        },
-        {
-          "href": "/react/hooks/firestore/useDisableNetworkMutation",
-          "title": "useDisableNetworkMutation"
-        },
-        {
-          "href": "/react/hooks/firestore/useEnableNetworkMutation",
-          "title": "useEnableNetworkMutation"
-        },
-        {
-          "href": "/react/hooks/firestore/useDocumentQuery",
-          "title": "useDocumentQuery"
-        },
-        {
-          "href": "/react/hooks/firestore/useGetAggregateFromServerQuery",
-          "title": "useGetAggregateFromServerQuery"
-        },
-        {
-          "href": "/react/hooks/firestore/useGetCountFromServerQuery",
-          "title": "useGetCountFromServerQuery"
-        },
-        {
-          "href": "/react/hooks/firestore/useRunTransactionMutation",
-          "title": "useRunTransactionMutation"
+          "title": "Getting Started",
+          "href": "/react/firestore"
         },
         {
-          "href": "/react/hooks/firestore/useWaitForPendingWritesQuery",
-          "title": "useWaitForPendingWritesQuery"
+          "group": "Hooks",
+          "pages": [
+            {
+              "href": "/react/firestore/hooks/useClearIndexedDbPersistenceMutation",
+              "title": "useClearIndexedDbPersistenceMutation"
+            },
+            {
+              "href": "/react/firestore/hooks/useCollectionQuery",
+              "title": "useCollectionQuery"
+            },
+            {
+              "href": "/react/firestore/hooks/useDisableNetworkMutation",
+              "title": "useDisableNetworkMutation"
+            },
+            {
+              "href": "/react/firestore/hooks/useEnableNetworkMutation",
+              "title": "useEnableNetworkMutation"
+            },
+            {
+              "href": "/react/firestore/hooks/useDocumentQuery",
+              "title": "useDocumentQuery"
+            },
+            {
+              "href": "/react/firestore/hooks/useGetAggregateFromServerQuery",
+              "title": "useGetAggregateFromServerQuery"
+            },
+            {
+              "href": "/react/firestore/hooks/useGetCountFromServerQuery",
+              "title": "useGetCountFromServerQuery"
+            },
+            {
+              "href": "/react/firestore/hooks/useRunTransactionMutation",
+              "title": "useRunTransactionMutation"
+            },
+            {
+              "href": "/react/firestore/hooks/useWaitForPendingWritesQuery",
+              "title": "useWaitForPendingWritesQuery"
+            }
+          ]
         }
       ]
     }

diff --git a/docs/index.mdx b/docs/index.mdx
@@ -3,6 +3,8 @@ title: TanStack Query Firebase
 description: TanStack Query Firebase provides a set of hooks for handling asynchronous tasks with Firebase in your applications.
 ---
 
+<Warning>The library is still heavily work-in-progress! Ensure your required functionality is supported before continuing.</Warning>
+
 When managing Firebase's asynchronous API calls within your application, state synchronization can become cumbersome in most applications. You will commonly find yourself handling loading states, error states, and data synchronization manually. 
 
 This library provides a hands-off approach to these problems, by leveraging the popular [TanStack Query](https://tanstack.com/query/latest) project. Out of the box, you get:
@@ -15,7 +17,7 @@ This library provides a hands-off approach to these problems, by leveraging the
 
 By combining Firebase with TanStack Query, you can make your app more resilient, performant, and scalable, all while writing less code.
 
-> Looking for React Query Firebase? Check out the [old branch](https://github.com/invertase/tanstack-query-firebase/tree/react-query-firebase).
+<Info>Looking for React Query Firebase? Check out the [old branch](https://github.com/invertase/tanstack-query-firebase/tree/react-query-firebase).</Info>
 
 ## Framework Installation
 

diff --git a/docs/react-query-firebase.mdx b/docs/react-query-firebase.mdx
@@ -0,0 +1,85 @@
+---
+title: Migrating to TanStack Query Firebase
+description: Migrating from the old React Query Firebase to the new TanStack Query Firebase.
+---
+
+The initial version of this project was called `React Query Firebase`, and built upon the
+older versions of *React Query*. Over the past couple of years, there's been many changes
+to the React Query library. 
+
+The most substantial change was renaming the libray from *React Query* to *TanStack Query*.
+
+The change brought about support for a wide array of framework support beyond React, including
+Vue, Solid, Angular, and Svelte. The API has also evolved during this time, with many improvements
+and new features.
+
+The Firebase API also evolved during this time, with new services such as Data Connect and the migration 
+from the compat API to the modular API.
+
+## react-query-firebase
+
+The `react-query-firebase` package was built to support React only, and was tightly coupled to
+the older versions of React Query. For example, the `react-query-firebase` NPN namespace allowed you
+to install a package per Firebase service, such as `@react-query-firebase/firestore`.
+
+Additionally, the API was designed to work with the older React Query API of supporting positional args 
+vs the newer object-based API:
+
+```tsx
+useFirestoreQuery(["products"]);
+// vs
+useFirestoreQuery({ queryKey: ["products"] });
+```
+
+## tanstack-query-firebase
+
+The `tanstack-query-firebase` package is built to support all frameworks which TanStack Query supports,
+although initially only React is supported.
+
+Altough still in development, the API is designed to work with the newer object-based API of TanStack Query,
+and also supports newer Firebase services such as Data Connect.
+
+### Realtime Subscription Issues
+
+Firebase supports realtime event subscriptions for many of its services, such as Firestore, Realtime Database and
+Authentication.
+
+The `react-query-firebase` package had a [limitation](https://github.com/invertase/tanstack-query-firebase/issues/25) whereby the hooks
+would not resubscribe whenever a component re-mounted.
+
+The initial version of `tanstack-query-firebase` currently opts-out of any realtime subscription hooks. This issue will be re-addressed
+once the core API is stable supporting all Firebase services.
+
+## Migration Steps
+
+Follow the steps below to migrate your application from `react-query-firebase` to `tanstack-query-firebase`:
+
+### 1. Install the new packages
+
+Due to the restructure of the package namespace, you will need to install the new packages:
+
+```bash
+npm i --save firebase @tanstack/react-query @tanstack-query-firebase/react
+```
+
+Remove any existing `@react-query-firebase/*` packages from your `package.json`.
+
+### 2. Update your imports
+
+Update any imports for your `react-query-firebase` hooks to the new `tanstack-query-firebase` hooks, for example for Firestore:
+
+```diff
+- import { useFirestoreDocument } from '@react-query-firebase/firestore';
++ import { useDocumentQuery } from '@tanstack-query-firebase/react/firestore';
+```
+
+### 3. Update your usage
+
+The older API followed the positional args pattern, whereas the new API follows the object-based pattern. Update your hooks to use the new pattern:
+
+```diff
+- useFirestoreDocument(["products"], ref);
++ useDocumentQuery(ref, {
++   queryKey: ["products"],
++ });
+```
diff --git a/docs/react/auth/hooks/useDeleteUserMutation.mdx b/docs/react/auth/hooks/useDeleteUserMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useDeleteUserMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useReloadMutation.mdx b/docs/react/auth/hooks/useReloadMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useReloadMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useSendSignInLinkToEmailMutation.mdx b/docs/react/auth/hooks/useSendSignInLinkToEmailMutation.mdx
@@ -0,0 +1,29 @@
+---
+title: useSendSignInLinkToEmailMutation
+---
+
+Send a sign-in link to a user's email address.
+
+## Usage
+
+```jsx
+import { useSendSignInLinkToEmailMutation } from "@tanstack-query-firebase/react/auth";
+import { auth } from "../firebase";
+
+function Component() {
+  const mutation = useSendSignInLinkToEmailMutation(auth, {
+    onSuccess: () => {
+      console.log("Sign-in link sent successfully!");
+    },
+  });
+
+  return (
+    <button
+      disabled={mutation.isPending}
+      onClick={() => mutation.mutate({ email: '...', actionCodeSettings: { ... } })}
+    >
+      Send Sign In Link
+    </button>
+  );
+}
+```
diff --git a/docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx b/docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useSignInAnonymouslyMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useSignInWithCredentialMutation.mdx b/docs/react/auth/hooks/useSignInWithCredentialMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useSignInWithCredentialMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx b/docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useSignInWithEmailAndPasswordMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useSignOutMutation.mdx b/docs/react/auth/hooks/useSignOutMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useSignOutMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useUpdateCurrentUserMutation.mdx b/docs/react/auth/hooks/useUpdateCurrentUserMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useUpdateCurrentUserMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/hooks/useVerifyPasswordResetCodeMutation.mdx b/docs/react/auth/hooks/useVerifyPasswordResetCodeMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useVerifyPasswordResetCodeMutation
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/auth/index.mdx b/docs/react/auth/index.mdx
@@ -0,0 +1,27 @@
+---
+title: Firebase Authentication
+---
+
+## Setup
+
+Before using the Tanstack Query Firebase hooks for Authentication, ensure you have configured your Firebase application
+to setup an Auth instance:
+
+```ts
+import { initializeApp } from "firebase/app";
+import { getAuth } from "firebase/auth";
+
+// Initialize your Firebase app
+initializeApp({ ... });
+
+// Get the Auth instance
+const auth = getAuth(app);
+```
+
+## Importing
+
+The package exports are available via the `@tanstack-query-firebase/react` package under the `auth` namespace:
+
+```ts
+import { useSignOutMutation } from "@tanstack-query-firebase/react/auth";
+```
diff --git a/docs/react/data-connect/hooks/useConnectMutation.mdx b/docs/react/data-connect/hooks/useConnectMutation.mdx
@@ -16,7 +16,7 @@ See [mutations](/react/data-connect/mutations) for more information.
 ## Usage
 
 ```jsx
-import { useConnectQuery } from "@tanstack-query-firebase/react";
+import { useConnectQuery } from "@tanstack-query-firebase/react/data-connect";
 import { createMovieRef } from "@your-package-name/your-connector";
 
 function Component() {

diff --git a/docs/react/data-connect/hooks/useConnectQuery.mdx b/docs/react/data-connect/hooks/useConnectQuery.mdx
@@ -16,7 +16,7 @@ See [querying](/react/data-connect/querying) for more information.
 ## Usage
 
 ```jsx
-import { useConnectQuery } from "@tanstack-query-firebase/react";
+import { useConnectQuery } from "@tanstack-query-firebase/react/data-connect";
 import { listMoviesQuery } from "@your-package-name/your-connector";
 
 function Component() {

diff --git a/.../useClearIndexedDbPersistenceMutation.mdx → .../useClearIndexedDbPersistenceMutation.mdx b/.../useClearIndexedDbPersistenceMutation.mdx → .../useClearIndexedDbPersistenceMutation.mdx
diff --git a/docs/react/firestore/hooks/useCollectionQuery.mdx b/docs/react/firestore/hooks/useCollectionQuery.mdx
@@ -0,0 +1,5 @@
+---
+title: useCollectionQuery
+---
+
+This documentation is a work in progress, check back soon.
diff --git a/docs/react/firestore/hooks/useDisableNetworkMutation.mdx b/docs/react/firestore/hooks/useDisableNetworkMutation.mdx
@@ -0,0 +1,5 @@
+---
+title: useDisableNetworkMutation
+---
+
+This documentation is a work in progress, check back soon.