React bindings for Galaxis.
yarn add @galaxis/react
This will also install and expose API of Galaxis Core.
The library is compiled to modern JS, but it should work in all reasonable browsers with the help of properly configured Babel.
Your client environment has to have AbortController
. You might need to polyfill it.
You also need a version of React that supports React Hooks.
⚠ Anything that is not documented here is not considered a part of public API and may change at any time.
ClientProvider
is used to configure and provide a Client
instance for the rest of the application.
interface AppProps {
client: AppClient;
}
const App: FC<AppProps> = ({ client }) => (
<ClientProvider client={client}>
<RestOfTheApp />
</ClientProvider>
);
Name | Type | Description | Required |
---|---|---|---|
client | Client |
A Client instance that will be used by the application. |
Yes |
preventOnHydrateCompleteCall | boolean |
By default, client.onHydrateComplete() will be called in useEffect . It should be fine in most cases, but you can use this option as an escape hatch and call client.onHydrateComplete() manually. |
No |
useClient
is used to retrieve the Client
instance that was passed to the Provider
. You can then use it to execute queries and mutations manually, access cache, etc.
const MyComponent: FC = () => {
const client = useClient();
const onClick = () => {
client.fetchQuery(query).then((data) => console.log(data));
};
return <button onClick={onClick}>Fetch the query manually</button>;
};
useQuery
is a thin wrapper for ObservableQuery
.
On rerender, the Query
objects fields are shallowly compared by the following rules:
- The
query.resource
fields are compared by the result of theclient.requestId()
call. - Functions are compared by their
.toString()
representation. - Everything else is compared by strict equality (
===
).
const MyComponent: FC = () => {
const { data } = useQuery(query);
return <div>{data?.value}</div>;
};
Name | Type | Description | Required |
---|---|---|---|
query | Query |
A query to maintain. | No |
ObservableQueryState & {refetch: observableQuery.refetch}
useMutation
is a thin wrapper for ObservableMutation
.
On rerender, the Mutation
object is just reassigned, because it doesn't lead to any side effects.
const MyComponent: FC = () => {
const [execute, state] = useMutation(mutation);
return <button onClick={execute}>Execute the mutation</button>;
};
Name | Type | Description | Required |
---|---|---|---|
mutation | Mutation |
A mutation to maintain. | No |
Name | Type | Description |
---|---|---|
execute | (mutation?: Mutation) => Promise<TData> |
A function for mutation execution. |
state | ObservableMutationState & {reset: observableMutation.reset} |
Mutation state and reset function. |
getDataFromTree()
is used on the server side to wait for queries to fill the cache with data and errors.
export default async function ssrMiddleware(_: Request, res: Response<unknown>) {
const client = getClient();
const app = createElement(App, { client });
await getDataFromTree(app);
const galaxisState = client.getCache().extract();
const html = createElement(Html, { content: renderToString(app), galaxisState });
res.send(renderToStaticMarkup(html));
}
Name | Type | Description | Required |
---|---|---|---|
tree | ReactNode |
The application. | Yes |
Promise<string>
. The promise resolves with the result of renderToStaticMarkup()
call.