diff --git a/docs.json b/docs.json index 0a60893..960b3ea 100644 --- 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 index 0b29f4c..d896587 100644 --- 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. --- +The library is still heavily work-in-progress! Ensure your required functionality is supported before continuing. + 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). +Looking for React Query Firebase? Check out the [old branch](https://github.com/invertase/tanstack-query-firebase/tree/react-query-firebase). ## Framework Installation diff --git a/docs/react-query-firebase.mdx b/docs/react-query-firebase.mdx new file mode 100644 index 0000000..7623a25 --- /dev/null +++ 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 new file mode 100644 index 0000000..24d6769 --- /dev/null +++ b/docs/react/auth/hooks/useDeleteUserMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useDeleteUserMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useReloadMutation.mdx b/docs/react/auth/hooks/useReloadMutation.mdx new file mode 100644 index 0000000..caa5b75 --- /dev/null +++ b/docs/react/auth/hooks/useReloadMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useReloadMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useSendSignInLinkToEmailMutation.mdx b/docs/react/auth/hooks/useSendSignInLinkToEmailMutation.mdx new file mode 100644 index 0000000..2e09752 --- /dev/null +++ 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 ( + + ); +} +``` diff --git a/docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx b/docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx new file mode 100644 index 0000000..ce1d2fc --- /dev/null +++ b/docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useSignInAnonymouslyMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useSignInWithCredentialMutation.mdx b/docs/react/auth/hooks/useSignInWithCredentialMutation.mdx new file mode 100644 index 0000000..b1ce9a4 --- /dev/null +++ b/docs/react/auth/hooks/useSignInWithCredentialMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useSignInWithCredentialMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx b/docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx new file mode 100644 index 0000000..b1a5541 --- /dev/null +++ b/docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useSignInWithEmailAndPasswordMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useSignOutMutation.mdx b/docs/react/auth/hooks/useSignOutMutation.mdx new file mode 100644 index 0000000..cbb8aff --- /dev/null +++ b/docs/react/auth/hooks/useSignOutMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useSignOutMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useUpdateCurrentUserMutation.mdx b/docs/react/auth/hooks/useUpdateCurrentUserMutation.mdx new file mode 100644 index 0000000..fe71c6a --- /dev/null +++ b/docs/react/auth/hooks/useUpdateCurrentUserMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useUpdateCurrentUserMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/hooks/useVerifyPasswordResetCodeMutation.mdx b/docs/react/auth/hooks/useVerifyPasswordResetCodeMutation.mdx new file mode 100644 index 0000000..e99ac7f --- /dev/null +++ b/docs/react/auth/hooks/useVerifyPasswordResetCodeMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useVerifyPasswordResetCodeMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/auth/index.mdx b/docs/react/auth/index.mdx new file mode 100644 index 0000000..ac583af --- /dev/null +++ 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 index 8bf0781..d4f6677 100644 --- 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 index cfe200f..e4034ec 100644 --- 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/docs/react/hooks/firestore/useClearIndexedDbPersistenceMutation.mdx b/docs/react/firestore/hooks/useClearIndexedDbPersistenceMutation.mdx similarity index 100% rename from docs/react/hooks/firestore/useClearIndexedDbPersistenceMutation.mdx rename to docs/react/firestore/hooks/useClearIndexedDbPersistenceMutation.mdx diff --git a/docs/react/firestore/hooks/useCollectionQuery.mdx b/docs/react/firestore/hooks/useCollectionQuery.mdx new file mode 100644 index 0000000..c4f5075 --- /dev/null +++ b/docs/react/firestore/hooks/useCollectionQuery.mdx @@ -0,0 +1,5 @@ +--- +title: useCollectionQuery +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useDisableNetworkMutation.mdx b/docs/react/firestore/hooks/useDisableNetworkMutation.mdx new file mode 100644 index 0000000..b446ba0 --- /dev/null +++ b/docs/react/firestore/hooks/useDisableNetworkMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useDisableNetworkMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useDocumentQuery.mdx b/docs/react/firestore/hooks/useDocumentQuery.mdx new file mode 100644 index 0000000..fe44c41 --- /dev/null +++ b/docs/react/firestore/hooks/useDocumentQuery.mdx @@ -0,0 +1,5 @@ +--- +title: useDocumentQuery +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useEnableNetworkMutation.mdx b/docs/react/firestore/hooks/useEnableNetworkMutation.mdx new file mode 100644 index 0000000..6570af2 --- /dev/null +++ b/docs/react/firestore/hooks/useEnableNetworkMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useEnableNetworkMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useGetAggregateFromServerQuery.mdx b/docs/react/firestore/hooks/useGetAggregateFromServerQuery.mdx new file mode 100644 index 0000000..28a9d32 --- /dev/null +++ b/docs/react/firestore/hooks/useGetAggregateFromServerQuery.mdx @@ -0,0 +1,5 @@ +--- +title: useGetAggregateFromServerQuery +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useGetCountFromServerQuery.mdx b/docs/react/firestore/hooks/useGetCountFromServerQuery.mdx new file mode 100644 index 0000000..6528ed2 --- /dev/null +++ b/docs/react/firestore/hooks/useGetCountFromServerQuery.mdx @@ -0,0 +1,5 @@ +--- +title: useGetCountFromServerQuery +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useRunTransactionMutation.mdx b/docs/react/firestore/hooks/useRunTransactionMutation.mdx new file mode 100644 index 0000000..0060f9d --- /dev/null +++ b/docs/react/firestore/hooks/useRunTransactionMutation.mdx @@ -0,0 +1,5 @@ +--- +title: useRunTransactionMutation +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/hooks/useWaitForPendingWritesQuery.mdx b/docs/react/firestore/hooks/useWaitForPendingWritesQuery.mdx new file mode 100644 index 0000000..d51e660 --- /dev/null +++ b/docs/react/firestore/hooks/useWaitForPendingWritesQuery.mdx @@ -0,0 +1,5 @@ +--- +title: useWaitForPendingWritesQuery +--- + +This documentation is a work in progress, check back soon. \ No newline at end of file diff --git a/docs/react/firestore/index.mdx b/docs/react/firestore/index.mdx new file mode 100644 index 0000000..bd49ca3 --- /dev/null +++ b/docs/react/firestore/index.mdx @@ -0,0 +1,27 @@ +--- +title: Firebase Firestore +--- + +## Setup + +Before using the Tanstack Query Firebase hooks for Firestore, ensure you have configured your Firebase application +to setup an Firestore instance: + +```ts +import { initializeApp } from "firebase/app"; +import { getFirestore } from "firebase/firestore"; + +// Initialize your Firebase app +initializeApp({ ... }); + +// Get the Firestore instance +const firestore = getFirestore(app); +``` + +## Importing + +The package exports are available via the `@tanstack-query-firebase/react` package under the `firestore` namespace: + +```ts +import { useDocumentQuery } from "@tanstack-query-firebase/react/firestore"; +```