Skip to content

Commit 18304ee

Browse files
EhespEhesp
committed
docs: Add stub docs
1 parent bb94a9c commit 18304ee

25 files changed

+341
-37
lines changed

‎docs.json

Lines changed: 88 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@
2525
{
2626
"href": "/",
2727
"title": "Introduction"
28+
},
29+
{
30+
"href": "/react-query-firebase",
31+
"title": "Migration Guide"
2832
}
2933
]
3034
},
@@ -43,8 +47,49 @@
4347
"group": "Authentication",
4448
"pages": [
4549
{
46-
"href": "/react/hooks/auth/useSignInAnonymouslyMutation",
47-
"title": "useSignInAnonymouslyMutation"
50+
"title": "Getting Started",
51+
"href": "/react/auth"
52+
},
53+
{
54+
"group": "Hooks",
55+
"pages": [
56+
{
57+
"title": "useDeleteUserMutation",
58+
"href": "/react/auth/hooks/useDeleteUserMutation"
59+
},
60+
{
61+
"title": "useReloadMutation",
62+
"href": "/react/auth/hooks/useReloadMutation"
63+
},
64+
{
65+
"title": "useSendSignInLinkToEmailMutation",
66+
"href": "/react/auth/hooks/useSendSignInLinkToEmailMutation"
67+
},
68+
{
69+
"title": "useSignInAnonymouslyMutation",
70+
"href": "/react/auth/hooks/useSignInAnonymouslyMutation"
71+
},
72+
{
73+
"title": "useSignInWithCredentialMutation",
74+
"href": "/react/auth/hooks/useSignInWithCredentialMutation"
75+
},
76+
{
77+
"title": "useSignInWithEmailAndPasswordMutation",
78+
"href": "/react/auth/hooks/useSignInWithEmailAndPasswordMutation"
79+
},
80+
{
81+
"title": "useSignOutMutation",
82+
"href": "/react/auth/hooks/useSignOutMutation"
83+
},
84+
{
85+
"title": "useUpdateCurrentUserMutation",
86+
"href": "/react/auth/hooks/useUpdateCurrentUserMutation"
87+
},
88+
{
89+
"title": "useVerifyPasswordResetCodeMutation",
90+
"href": "/react/auth/hooks/useVerifyPasswordResetCodeMutation"
91+
}
92+
]
4893
}
4994
]
5095
},
@@ -88,40 +133,49 @@
88133
"group": "Firestore",
89134
"pages": [
90135
{
91-
"href": "/react/hooks/firestore/useClearIndexedDbPersistenceMutation",
92-
"title": "useClearIndexedDbPersistenceMutation"
93-
},
94-
{
95-
"href": "/react/hooks/firestore/useCollectionQuery",
96-
"title": "useCollectionQuery"
97-
},
98-
{
99-
"href": "/react/hooks/firestore/useDisableNetworkMutation",
100-
"title": "useDisableNetworkMutation"
101-
},
102-
{
103-
"href": "/react/hooks/firestore/useEnableNetworkMutation",
104-
"title": "useEnableNetworkMutation"
105-
},
106-
{
107-
"href": "/react/hooks/firestore/useDocumentQuery",
108-
"title": "useDocumentQuery"
109-
},
110-
{
111-
"href": "/react/hooks/firestore/useGetAggregateFromServerQuery",
112-
"title": "useGetAggregateFromServerQuery"
113-
},
114-
{
115-
"href": "/react/hooks/firestore/useGetCountFromServerQuery",
116-
"title": "useGetCountFromServerQuery"
117-
},
118-
{
119-
"href": "/react/hooks/firestore/useRunTransactionMutation",
120-
"title": "useRunTransactionMutation"
136+
"title": "Getting Started",
137+
"href": "/react/firestore"
121138
},
122139
{
123-
"href": "/react/hooks/firestore/useWaitForPendingWritesQuery",
124-
"title": "useWaitForPendingWritesQuery"
140+
"group": "Hooks",
141+
"pages": [
142+
{
143+
"href": "/react/firestore/hooks/useClearIndexedDbPersistenceMutation",
144+
"title": "useClearIndexedDbPersistenceMutation"
145+
},
146+
{
147+
"href": "/react/firestore/hooks/useCollectionQuery",
148+
"title": "useCollectionQuery"
149+
},
150+
{
151+
"href": "/react/firestore/hooks/useDisableNetworkMutation",
152+
"title": "useDisableNetworkMutation"
153+
},
154+
{
155+
"href": "/react/firestore/hooks/useEnableNetworkMutation",
156+
"title": "useEnableNetworkMutation"
157+
},
158+
{
159+
"href": "/react/firestore/hooks/useDocumentQuery",
160+
"title": "useDocumentQuery"
161+
},
162+
{
163+
"href": "/react/firestore/hooks/useGetAggregateFromServerQuery",
164+
"title": "useGetAggregateFromServerQuery"
165+
},
166+
{
167+
"href": "/react/firestore/hooks/useGetCountFromServerQuery",
168+
"title": "useGetCountFromServerQuery"
169+
},
170+
{
171+
"href": "/react/firestore/hooks/useRunTransactionMutation",
172+
"title": "useRunTransactionMutation"
173+
},
174+
{
175+
"href": "/react/firestore/hooks/useWaitForPendingWritesQuery",
176+
"title": "useWaitForPendingWritesQuery"
177+
}
178+
]
125179
}
126180
]
127181
}

‎docs/index.mdx

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: TanStack Query Firebase
33
description: TanStack Query Firebase provides a set of hooks for handling asynchronous tasks with Firebase in your applications.
44
---
55

6+
<Warning>The library is still heavily work-in-progress! Ensure your required functionality is supported before continuing.</Warning>
7+
68
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.
79

810
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
1517

1618
By combining Firebase with TanStack Query, you can make your app more resilient, performant, and scalable, all while writing less code.
1719

18-
> Looking for React Query Firebase? Check out the [old branch](https://github.com/invertase/tanstack-query-firebase/tree/react-query-firebase).
20+
<Info>Looking for React Query Firebase? Check out the [old branch](https://github.com/invertase/tanstack-query-firebase/tree/react-query-firebase).</Info>
1921

2022
## Framework Installation
2123

‎docs/react-query-firebase.mdx

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Migrating to TanStack Query Firebase
3+
description: Migrating from the old React Query Firebase to the new TanStack Query Firebase.
4+
---
5+
6+
The initial version of this project was called `React Query Firebase`, and built upon the
7+
older versions of *React Query*. Over the past couple of years, there's been many changes
8+
to the React Query library.
9+
10+
The most substantial change was renaming the libray from *React Query* to *TanStack Query*.
11+
12+
The change brought about support for a wide array of framework support beyond React, including
13+
Vue, Solid, Angular, and Svelte. The API has also evolved during this time, with many improvements
14+
and new features.
15+
16+
The Firebase API also evolved during this time, with new services such as Data Connect and the migration
17+
from the compat API to the modular API.
18+
19+
## react-query-firebase
20+
21+
The `react-query-firebase` package was built to support React only, and was tightly coupled to
22+
the older versions of React Query. For example, the `react-query-firebase` NPN namespace allowed you
23+
to install a package per Firebase service, such as `@react-query-firebase/firestore`.
24+
25+
Additionally, the API was designed to work with the older React Query API of supporting positional args
26+
vs the newer object-based API:
27+
28+
```tsx
29+
useFirestoreQuery(["products"]);
30+
// vs
31+
useFirestoreQuery({ queryKey: ["products"] });
32+
```
33+
34+
## tanstack-query-firebase
35+
36+
The `tanstack-query-firebase` package is built to support all frameworks which TanStack Query supports,
37+
although initially only React is supported.
38+
39+
Altough still in development, the API is designed to work with the newer object-based API of TanStack Query,
40+
and also supports newer Firebase services such as Data Connect.
41+
42+
### Realtime Subscription Issues
43+
44+
Firebase supports realtime event subscriptions for many of its services, such as Firestore, Realtime Database and
45+
Authentication.
46+
47+
The `react-query-firebase` package had a [limitation](https://github.com/invertase/tanstack-query-firebase/issues/25) whereby the hooks
48+
would not resubscribe whenever a component re-mounted.
49+
50+
The initial version of `tanstack-query-firebase` currently opts-out of any realtime subscription hooks. This issue will be re-addressed
51+
once the core API is stable supporting all Firebase services.
52+
53+
## Migration Steps
54+
55+
Follow the steps below to migrate your application from `react-query-firebase` to `tanstack-query-firebase`:
56+
57+
### 1. Install the new packages
58+
59+
Due to the restructure of the package namespace, you will need to install the new packages:
60+
61+
```bash
62+
npm i --save firebase @tanstack/react-query @tanstack-query-firebase/react
63+
```
64+
65+
Remove any existing `@react-query-firebase/*` packages from your `package.json`.
66+
67+
### 2. Update your imports
68+
69+
Update any imports for your `react-query-firebase` hooks to the new `tanstack-query-firebase` hooks, for example for Firestore:
70+
71+
```diff
72+
- import { useFirestoreDocument } from '@react-query-firebase/firestore';
73+
+ import { useDocumentQuery } from '@tanstack-query-firebase/react/firestore';
74+
```
75+
76+
### 3. Update your usage
77+
78+
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:
79+
80+
```diff
81+
- useFirestoreDocument(["products"], ref);
82+
+ useDocumentQuery(ref, {
83+
+ queryKey: ["products"],
84+
+ });
85+
```

‎docs/react/auth/hooks/useDeleteUserMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useDeleteUserMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

‎docs/react/auth/hooks/useReloadMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useReloadMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

‎docs/react/auth/hooks/useSendSignInLinkToEmailMutation.mdx

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: useSendSignInLinkToEmailMutation
3+
---
4+
5+
Send a sign-in link to a user's email address.
6+
7+
## Usage
8+
9+
```jsx
10+
import { useSendSignInLinkToEmailMutation } from "@tanstack-query-firebase/react/auth";
11+
import { auth } from "../firebase";
12+
13+
function Component() {
14+
const mutation = useSendSignInLinkToEmailMutation(auth, {
15+
onSuccess: () => {
16+
console.log("Sign-in link sent successfully!");
17+
},
18+
});
19+
20+
return (
21+
<button
22+
disabled={mutation.isPending}
23+
onClick={() => mutation.mutate({ email: '...', actionCodeSettings: { ... } })}
24+
>
25+
Send Sign In Link
26+
</button>
27+
);
28+
}
29+
```

‎docs/react/auth/hooks/useSignInAnonymouslyMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useSignInAnonymouslyMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

‎docs/react/auth/hooks/useSignInWithCredentialMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useSignInWithCredentialMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

‎docs/react/auth/hooks/useSignInWithEmailAndPasswordMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useSignInWithEmailAndPasswordMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

‎docs/react/auth/hooks/useSignOutMutation.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: useSignOutMutation
3+
---
4+
5+
This documentation is a work in progress, check back soon.

0 commit comments

Comments
 (0)