Skip to content

Commit 0d72bef

Browse files
EhespEhesp
committed
docs: Update data connect docs
1 parent 242df90 commit 0d72bef

File tree

7 files changed

+383
-16
lines changed

7 files changed

+383
-16
lines changed

‎docs.json

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,33 @@
5353
"group": "Data Connect",
5454
"pages": [
5555
{
56-
"href": "/react/hooks/data-connect/useConnectQuery",
57-
"title": "useConnectQuery"
56+
"title": "Getting Started",
57+
"href": "/react/data-connect"
5858
},
5959
{
60-
"href": "/react/hooks/data-connect/useConnectMutation",
61-
"title": "useConnectMutation"
60+
"title": "Querying",
61+
"href": "/react/data-connect/querying"
62+
},
63+
{
64+
"title": "Mutations",
65+
"href": "/react/data-connect/mutations"
66+
},
67+
{
68+
"title": "Server Side Rendering",
69+
"href": "/react/data-connect/server-side-rendering"
70+
},
71+
{
72+
"group": "Hooks",
73+
"pages": [
74+
{
75+
"title": "useConnectQuery",
76+
"href": "/react/data-connect/hooks/useConnectQuery"
77+
},
78+
{
79+
"title": "useConnectMutation",
80+
"href": "/react/data-connect/hooks/useConnectMutation"
81+
}
82+
]
6283
}
6384
]
6485
},

‎docs/react/hooks/data-connect/useConnectMutation.mdx renamed to ‎docs/react/data-connect/hooks/useConnectMutation.mdx

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@ title: useConnectMutation
33
---
44

55
`useConnectMutation` is a hook designed to simplify handling mutations (creating, updating, deleting) with Firebase Data Connect.
6-
This hook integrates with [Firebase Data Connect](https://firebase.google.com/docs/data-connect), which uses GraphQL to interact with a PostgreSQL database (via Cloud SQL) for secure, scalable data operations.
7-
The hook manages the mutation process and provides an easy-to-use interface to manage loading, success, and error states in your React application.
6+
7+
See [mutations](/react/data-connect/mutations) for more information.
88

99
## Features
1010

1111
- Simplifies mutation handling for <b>create</b>, <b>update</b>, and <b>delete</b> operations using Firebase Data Connect.
1212
- Provides <b>type-safe</b> handling of mutations based on your Firebase Data Connect schema.
13-
- Automatically manages <b>loading</b>, <b>success</b>, and <b>error</b> states for mutations.
13+
- Automatically manages <b>pending</b>, <b>success</b>, and <b>error</b> states for mutations.
1414
- Supports <b>optimistic updates</b> and <b>caching</b> to improve user experience and performance.
1515

1616
## Usage
@@ -23,21 +23,29 @@ function Component() {
2323
const { mutate, isPending, isSuccess, isError, error } =
2424
useConnectMutation(createMovieRef);
2525

26-
const handleSubmit = async (movieData) => {
27-
try {
28-
await mutate(movieData);
29-
} catch (err) {
30-
console.error("Failed to add movie:", err);
31-
}
26+
const handleFormSubmit = (e: React.FormEvent) => {
27+
e.preventDefault();
28+
const data = new FormData(e.target as HTMLFormElement);
29+
30+
mutate({
31+
title: data.get("title") as string,
32+
imageUrl: data.get("imageUrl") as string,
33+
genre: data.get("genre") as string,
34+
});
3235
};
3336

3437
if (isPending) return <div>Adding movie...</div>;
38+
3539
if (isError) return <div>Error: {error.message}</div>;
3640

3741
return (
3842
<div>
3943
{isSuccess && <div>Movie added successfully!</div>}
40-
<form onSubmit={(e) => handleSubmit(e.target)}>
44+
<form onSubmit={handleFormSubmit}>
45+
<input type="text" name="title" placeholder="Title" />
46+
<input type="text" name="genre" placeholder="Genre" />
47+
<input type="text" name="imageUrl" placeholder="Image URL" />
48+
4149
{/* Form fields for movie data */}
4250
<button type="submit" disabled={isPending}>
4351
Add Movie

‎docs/react/hooks/data-connect/useConnectQuery.mdx renamed to ‎docs/react/data-connect/hooks/useConnectQuery.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ title: useConnectQuery
33
---
44

55
`useConnectQuery` is a hook designed to simplify data fetching and state management with Firebase Data Connect.
6-
This hook integrates with [Firebase Data Connect](https://firebase.google.com/docs/data-connect), which leverages GraphQL to interact with a PostgreSQL database (via Cloud SQL) for secure, scalable data operations.
7-
The hook simplifies the process of querying data from Firebase Data Connect and provides an easy-to-use interface to manage loading, success, and error states in your React application.
6+
7+
See [querying](/react/data-connect/querying) for more information.
88

99
## Features
1010

‎docs/react/data-connect/index.mdx

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Firebase Data Connect
3+
---
4+
5+
Firebase Data Connect is a relational database service for mobile and web apps that lets you build and scale using a fully-managed PostgreSQL database powered by Cloud SQL. It provides secure schema, query and mutation management using GraphQL technology that integrates well with Firebase Authentication.
6+
7+
To get started, ensure you have setup your Firebase project and have the Data Connect setup in your project. To learn more,
8+
follow the [Firebase Data Connect documentation](https://firebase.google.com/docs/data-connect/quickstart).
9+
10+
## Setup
11+
12+
Before using the Tanstack Query Firebase hooks for Data Connect, ensure you have configured your application using your chosen connector:
13+
14+
```ts
15+
import { connectorConfig } from "../../dataconnect/default-connector";
16+
import { initializeApp } from "firebase/app";
17+
import { getDataConnect } from "firebase/data-connect";
18+
19+
// Initialize your Firebase app
20+
initializeApp({ ... });
21+
22+
// Get the Data Connect instance
23+
const dataConnect = getDataConnect(connectorConfig);
24+
25+
// Optionally, connect to the Data Connect Emulator
26+
connectDataConnectEmulator(dataConnect, "localhost", 9399);
27+
```
28+
29+
## Importing
30+
31+
The package exports are available via the `@tanstack-query-firebase/react` package under the `data-connect` namespace:
32+
33+
```ts
34+
import { useConnectQuery } from "@tanstack-query-firebase/react/data-connect";
35+
```
36+
37+
## Basic Usage
38+
39+
To use the Tanstack Query Firebase hooks for Data Connect, you can use the `useConnectQuery` hook to fetch data from the database:
40+
41+
```tsx
42+
import { useConnectQuery } from "@tanstack-query-firebase/react";
43+
import { listMoviesRef } from "../../dataconnect/default-connector";
44+
45+
function Component() {
46+
const { data, isPending, isSuccess, isError, error } = useConnectQuery(
47+
listMoviesRef()
48+
);
49+
50+
if (isPending) return <div>Loading...</div>;
51+
52+
if (isError) return <div>Error: {error.message}</div>;
53+
54+
return <div>{isSuccess && <ul>{data.movies.map((movie) => <li key={movie.id}>{movie.title}</li>)}</ul>}</div>;
55+
}
56+
```
57+
58+
The hooks will automatically infer the data type from the connector and the query and automtically create a [query key](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for the query.
59+
60+
## Learning more
61+
62+
To learn more about the Data Connect hooks, check out the following pages:
63+
64+
- [Querying](/react/data-connect/querying)
65+
- [Mutations](/react/data-connect/mutations)
66+
- [Server Side Rendering](/react/data-connect/server-side-rendering)
67+

‎docs/react/data-connect/mutations.mdx

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Mutations
3+
description: Learn how to mutate data in Firebase Data Connect using the Tanstack Query Firebase hooks.
4+
---
5+
6+
## Mutating Data
7+
8+
To mutate data in Firebase Data Connect, you can use the `useConnectMutation` hook.
9+
10+
```tsx
11+
import { useConnectMutation } from "@tanstack-query-firebase/react";
12+
import { createMovieRef } from "@dataconnect/default-connector";
13+
14+
function Component() {
15+
const createMovie = useConnectMutation(
16+
createMovieRef
17+
);
18+
19+
return (
20+
<button
21+
disabled={createMovie.isPending}
22+
onClick={() => {
23+
createMovie.mutate({
24+
title: 'John Wick',
25+
genre: "Action",
26+
imageUrl: "https://example.com/image.jpg",
27+
});
28+
}}
29+
>
30+
{createMovie.isPending ? "Creating..." : "Create Movie"}
31+
</button>
32+
);
33+
}
34+
```
35+
36+
## Invalidating Queries
37+
38+
The hook provides an additional [mutation option](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) called `invalidate`. This option accepts a list of query references which will be automatically invalidated when the mutation is successful.
39+
40+
```tsx
41+
const createMovie = useConnectMutation(createMovieRef, {
42+
invalidate: [getMovieRef],
43+
});
44+
```
45+
46+
### Implicit references
47+
48+
The above example provides a `getMovieRef` instance to the invalidate array. By default this will invalidate all queries that cached via the `getMovieRef` reference, for example the following query references will be invalidated:
49+
50+
```tsx
51+
getMovieRef({ id: "1"});
52+
getMovieRef({ id: "2"});
53+
```
54+
55+
### Explicit references
56+
57+
You can also provide explicit references to the invalidate array, for example:
58+
59+
```tsx
60+
const createMovie = useConnectMutation(createMovieRef, {
61+
invalidate: [getMovieRef({ id: "1" })],
62+
});
63+
```
64+
65+
In this case only the query reference `getMovieRef({ id: "1" })` will be invalidated.
66+
67+
## Overriding the mutation key
68+
69+
### Metadata
70+
71+
Along with the data, the hook will also return the `ref`, `source`, and `fetchTime` metadata from the mutation.
72+
73+
```tsx
74+
const createMovie = useConnectMutation(createMovieRef);
75+
76+
const data = await createMovie.mutateAsync({
77+
title: 'John Wick',
78+
genre: "Action",
79+
imageUrl: "https://example.com/image.jpg",
80+
});
81+
82+
console.log(data.ref);
83+
console.log(data.source);
84+
console.log(data.fetchTime);
85+
```

‎docs/react/data-connect/querying.mdx

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Querying
3+
description: Learn how to query data from Firebase Data Connect using the Tanstack Query Firebase hooks.
4+
---
5+
6+
## Querying Data
7+
8+
To query data from Firebase Data Connect, you can use the `useConnectQuery` hook. This hook will automatically infer the data type from the connector and the query and automtically create a [query key](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for the query.
9+
10+
```tsx
11+
import { useConnectQuery } from "@tanstack-query-firebase/react";
12+
import { listMoviesRef } from "@dataconnect/default-connector";
13+
14+
function Component() {
15+
const { data, isPending, isSuccess, isError, error } = useConnectQuery(
16+
listMoviesRef()
17+
);
18+
}
19+
```
20+
21+
### Query options
22+
23+
To leverage the full power of Tanstack Query, you can pass in query options to the `useConnectQuery` hook, for example to refetch the query on a interval:
24+
25+
```tsx
26+
const { data, isPending, isSuccess, isError, error } = useConnectQuery(
27+
listMoviesRef(),
28+
{
29+
refetchInterval: 1000,
30+
}
31+
);
32+
```
33+
34+
The hook extends the [`useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) hook, so you can learn more about the available options by reading the [Tanstack Query documentation](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
35+
36+
### Overriding the query key
37+
38+
To override the query key, you can pass in a custom query key to the `useConnectQuery` hook:
39+
40+
```tsx
41+
const { data, isPending, isSuccess, isError, error } = useConnectQuery(
42+
getMovieRef({ id: "1" }),
43+
{
44+
queryKey: ["movies", "1"],
45+
}
46+
);
47+
```
48+
49+
Note that overriding the query key could mean your query is no longer synchronized with mutation invalidations or server side rendering pre-fetching.
50+
51+
### Initial data
52+
53+
If your application has already fetched a data from Data Connect, you can instead pass the `QueryResult` instance to the hook. This will instead set the `initialData` option on the hook:
54+
55+
```tsx
56+
// Elsewhere in your application
57+
const movies = await executeQuery(listMoviesRef());
58+
59+
// ...
60+
61+
function Component(props: { movies: QueryResult<ListMoviesData, unknown> }) {
62+
const { data, isPending, isSuccess, isError, error } = useConnectQuery(
63+
props.movies
64+
);
65+
}
66+
```
67+
68+
The hook will immediately have data available, and immediately refetch the data when the component is mounted. This behavior can be contolled by providing a `staleTime` value to the hook or Query Client.
69+
70+
### Metadata
71+
72+
Along with the data, the hook will also return the `ref`, `source`, and `fetchTime` metadata from the query.
73+
74+
```tsx
75+
const { data } = useConnectQuery(listMoviesRef());
76+
77+
console.log(data?.ref);
78+
console.log(data?.source);
79+
console.log(data?.fetchTime);
80+
```

0 commit comments

Comments
 (0)