Skip to content

Commit c59f5b0

Browse files
js2mejs2me
committed
docs: create docs using docusaurus
1 parent 026d2d9 commit c59f5b0

File tree

22 files changed

+12478
-1
lines changed

22 files changed

+12478
-1
lines changed

‎.eslintignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,5 @@ jsconfig.json
1616
.eslintrc.cjs
1717
post-build.mjs
1818
coverage
19-
vitest.config.ts
19+
vitest.config.ts
20+
website

‎.github/workflows/github-pages.yaml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
8+
jobs:
9+
build:
10+
name: Build Docusaurus
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
16+
- uses: pnpm/action-setup@v4
17+
name: Install pnpm
18+
with:
19+
run_install: false
20+
21+
- name: Install Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: 20
25+
cache: 'pnpm'
26+
27+
- name: Install dependencies
28+
run: cd website && pnpm install
29+
- name: Build website
30+
run: pnpm website:build
31+
32+
- name: Upload Build Artifact
33+
uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: website/build
36+
37+
deploy:
38+
name: Deploy to GitHub Pages
39+
needs: build
40+
41+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
42+
permissions:
43+
pages: write # to deploy to Pages
44+
id-token: write # to verify the deployment originates from an appropriate source
45+
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
50+
runs-on: ubuntu-latest
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v4

‎docs/API/Mobx Mutation/overview.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: mobx-mutation-overview
3+
title: MobxMutation overview
4+
sidebar_label: Overview
5+
sidebar_position: 1
6+
slug: /api/mobx-mutation/overview
7+
---

‎docs/API/Mobx Query Client/overview.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: mobx-query-client-overview
3+
title: MobxQueryClient overview
4+
sidebar_label: Overview
5+
sidebar_position: 1
6+
slug: /api/mobx-query-client/overview
7+
---

‎docs/API/Mobx Query/overview.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: mobx-query-overview
3+
title: MobxQuery overview
4+
sidebar_label: Overview
5+
sidebar_position: 1
6+
slug: /api/mobx-query/overview
7+
---

‎docs/Getting Started/decorators.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
id: decorators
3+
title: Decorators
4+
sidebar_label: Decorators
5+
description: decorators
6+
slug: /getting-started/decorators
7+
sidebar_position: 3
8+
---
9+
10+
# MobX decorators and other
11+
12+
If you want to use decorators with query\mutation instances you need to configure your bundle.
13+
All next documentation contains code with accessor decorators which works using only with Babel. You can replace them with [`makeObservable`](https://mobx.js.org/observable-state.html#makeobservable), [`extendObservable`](https://mobx.js.org/api.html#extendobservable) MobX functions
14+
15+
16+

‎docs/Getting Started/installation.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
id: installation
3+
title: Installation
4+
sidebar_label: Installation
5+
description: Installation guide
6+
slug: /getting-started/installation
7+
sidebar_position: 2
8+
---
9+
10+
## Requirements
11+
- MobX 6+ (required)
12+
- @tanstack/query-core v5+ (dependency, will be installed together with package)
13+
14+
## Package installation
15+
Install with your preferred package manager:
16+
17+
```bash
18+
pnpm add mobx-tanstack-query mobx
19+
```
20+
```bash
21+
npm install mobx-tanstack-query mobx
22+
```
23+
```bash
24+
yarn add mobx-tanstack-query mobx
25+
```
26+
27+
### Module Compatibility
28+
29+
`mobx-tanstack-query` uses ESM modules with `NodeNext` resolution.
30+

‎docs/Getting Started/overview.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: overview
3+
title: Overview
4+
sidebar_label: Overview
5+
sidebar_position: 1
6+
slug: /getting-started
7+
---
8+
**mobx-tanstack-query** is a library for integration [tanstack-query](https://tanstack.com/query/latest/docs/framework/react/overview) library with `MobX`.
9+
Combines the power of `TanStack Query`’s caching and async state management with `MobX`’s reactivity.
10+
11+
## Motivation
12+
1. **Universal Approach**
13+
Enables using `TanStack Query` in `MobX`-driven projects, including non-React environments (e.g., Vue, Svelte, or vanilla JS).
14+
15+
2. **State Synchronization**
16+
Automatically syncs `TanStack Query`’s cache state with `MobX` reactive systems, ensuring data consistency.
17+
18+
3. **Flexible Integration**
19+
Lets you use `TanStack Query`’s familiar API alongside `MobX` reactions for automatic cache invalidation and refetching.
20+
21+
4. **Performance Optimization**
22+
Combines `TanStack Query`’s efficient query caching with `MobX`’s granular updates to minimize unnecessary re-renders.
23+
24+
## Pros and cons
25+
26+
Pros:
27+
- `MobX` reactivity intergration with `TanStack Query` power.
28+
29+
Cons:
30+
- Requires basic understanding of `MobX` reactions.
31+
- Adds a small bundle size overhead (~2KB) for the integration layer.
32+
- Some `React`-specific `TanStack Query` features are unavailable.
33+

‎docs/Getting Started/usage.mdx‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
id: usage
3+
title: Usage
4+
sidebar_label: Usage
5+
description: usage
6+
slug: /getting-started/usage
7+
sidebar_position: 4
8+
---
9+
10+
# Usage
11+
12+
## 1. Create [`MobxQueryClient`](/api/mobx-query-client/overview) instance
13+
14+
```ts title="@/shared/lib/tanstack-query/query-client.ts"
15+
import { hashKey } from '@tanstack/query-core';
16+
import { MobxQueryClient } from 'mobx-tanstack-query';
17+
18+
const MAX_FAILURE_COUNT = 3;
19+
20+
export const queryClient = new MobxQueryClient({
21+
defaultOptions: {
22+
queries: {
23+
throwOnError: true,
24+
queryKeyHashFn: hashKey,
25+
refetchOnWindowFocus: 'always',
26+
refetchOnReconnect: 'always',
27+
staleTime: 5 * 60 * 1000,
28+
retry: (failureCount, error) => {
29+
if ('status' in error && Number(error.status) >= 500) {
30+
return MAX_FAILURE_COUNT - failureCount > 0;
31+
}
32+
return false;
33+
},
34+
},
35+
mutations: {
36+
throwOnError: true,
37+
},
38+
},
39+
});
40+
```
41+
42+
Or you can use [`QueryClient`](https://tanstack.com/query/v5/docs/reference/QueryClient) instance from TanStack Query core package.
43+
But you need to `mount` that instance of `QueryClient`
44+
45+
```ts
46+
queryClient.mount(); // enable all subscriptions for online\offline and window focus/blur
47+
```
48+
49+
50+
## 2. Use
51+
52+
```ts
53+
const petsListQuery = new MobxQuery({
54+
queryClient,
55+
queryKey: ['pets'],
56+
queryFn: async ({ signal, queryKey }) => {
57+
const response = await petsApi.fetchPets({ signal });
58+
return response.data;
59+
},
60+
});
61+
62+
const addPetsMutation = new MobxMutation({
63+
queryClient,
64+
mutationFn: async (payload: { petName: string }) => {
65+
const response = await petsApi.createPet(payload);
66+
return response.data;
67+
},
68+
69+
onSuccess: (data) => {
70+
rootStore.notifications.push({
71+
type: 'success',
72+
title: `Pet created successfully with name ${data.name}`,
73+
});
74+
petsListQuery.invalidate();
75+
},
76+
onError: (error) => {
77+
rootStore.notifications.push({
78+
type: 'danger',
79+
title: 'Failed to create pet',
80+
});
81+
}
82+
});
83+
84+
addPetsMutation.mutate({ petName: 'fluffy' });
85+
```
86+
87+
88+
# Another usage or `mobx-tanstack-query/preset`
89+
90+
This sub folder is contains already configured [instance of QueryClient](/src/preset/query-client.ts) with [this configuration](/src/preset/configs/default-query-client-config.ts) and needed to reduce your boilerplate with more compact way.
91+
Every parameter in configuration you can override using this construction
92+
```ts
93+
import { queryClient } from "mobx-tanstack-query/preset";
94+
95+
const defaultOptions = queryClient.getDefaultOptions();
96+
defaultOptions.queries!.refetchOnMount = true;
97+
queryClient.setDefaultOptions({ ...defaultOptions })
98+
```
99+
100+
101+
P.S. Overriding default options should be written before start whole application
102+
103+
104+
### `createQuery(queryFn, otherOptionsWithoutFn?)`
105+
106+
This is alternative for `new MobxQuery()`. Example:
107+
108+
```ts
109+
import { createQuery } from "mobx-tanstack-query/preset";
110+
111+
const query = createQuery(async ({ signal, queryKey }) => {
112+
const response = await petsApi.fetchPets({ signal });
113+
return response.data;
114+
}, {
115+
queryKey: ['pets'],
116+
})
117+
```
118+
119+
### `createMutation(mutationFn, otherOptionsWithoutFn?)`
120+
121+
This is alternative for `new MobxMutation()`. Example:
122+
123+
```ts
124+
import { createMutation } from "mobx-tanstack-query/preset";
125+
126+
const mutation = createMutation(async (payload: { petName: string }) => {
127+
const response = await petsApi.createPet(payload);
128+
return response.data;
129+
})
130+
```
131+
132+
133+
### `createInfiniteQuery(queryFn, otherOptionsWithoutFn?)`
134+
135+
This is alternative for `new MobxInfiniteQuery()`. Example:
136+
137+
```ts
138+
import { createInfiniteQuery } from "mobx-tanstack-query/preset";
139+
140+
const query = createInfiniteQuery(async ({ signal, queryKey }) => {
141+
const response = await petsApi.fetchPets({ signal });
142+
return response.data;
143+
})
144+
```
145+

‎docs/Other/Project Exmples.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
id: project-examples
3+
title: Project Examples
4+
sidebar_label: Project Examples
5+
sidebar_position: 1
6+
slug: /other/project-examples
7+
---
8+
9+
## **HTTP Status Codes**
10+
Simple usage `MobX` Tanstack queries to fetch JSON data from GitHub
11+
12+
_Links_:
13+
- Source: https://github.com/js2me/http-status-codes
14+
- GitHub Pages: https://js2me.github.io/http-status-codes/#/

0 commit comments

Comments
 (0)