🚀Getting Started⬡Atomic Design⚡React Query
⚡

React Query

TanStack Query v5 — Fetcher → Repository → Queries → Controller → UI

When you enable React Query, AtomKit scaffolds a full 5-layer architecture matching production patterns. Each layer has a single responsibility — from the HTTP client all the way to the presentational UI.

📦AtomKit generates 7 files inside the downloaded zip: fetcher, items repository, QueryProvider, itemsQueries, ItemsController, AllItemsUI, and an example page wiring them together. Extract the zip and run npm install to get started.

What AtomKit Generates

📄Generated files (React Query enabled)
src/
├── common/
│   └── fetcher.js               ← singleton HTTP client (getData, postData, deleteData…)
│
├── repositories/
│   └── items.js                 ← Items service class — wraps fetcher with /api/items endpoint
│
├── providers/
│   └── QueryProvider.jsx        ← wraps app with QueryClient + Devtools
│
├── queries/
│   └── itemsQueries.js          ← React Query hooks calling the repository
│
├── controller/
│   └── ItemsController.jsx       ← consumes queries, manages state, cloneElement to children
│
├── components/
│   └── pages/
│       └── items/
│           └── AllItemsUI.jsx   ← pure presentational component
│
└── app/
    ├── items/
    │   └── page.jsx             ← example page: Controller + UI wired together
    └── layout.jsx               ← updated with <QueryProvider>

The 5-Layer Architecture

Fetcher

Singleton HTTP client — getData, postData, deleteData.

common/fetcher.js
Repository

Service class per resource — wraps fetcher with endpoints.

repositories/items.js
Queries

One file per feature — React Query hooks call the repository.

queries/itemsQueries.js
Controller

Consume queries, manage state, cloneElement to children.

controller/ItemsController.jsx
UI

Pure components — receive props, render JSX, zero data logic.

components/pages/items/AllItemsUI.jsx
📄Data flow
  Fetcher          Repository        Queries            Controller          UI
┌────────────┐  ┌──────────────┐  ┌────────────────┐  ┌───────────────┐  ┌──────────────┐
│ fetcher.js │◀─│ items.js     │◀─│ itemsQueries   │◀─│ ItemsController│─▶│ AllItemsUI   │
│            │  │              │  │                │  │               │  │              │
│ getData()  │  │ getAllItems() │  │ useItemsGet..  │  │ consumes hooks│  │ receives all │
│ postData() │  │ postItem()   │  │ useItemsPost.. │  │ manages state │  │ as props     │
│ deleteData │  │ deleteItem() │  │ useItemsDel..  │  │ cloneElement  │  │ renders JSX  │
└────────────┘  └──────────────┘  └────────────────┘  └───────────────┘  └──────────────┘

Layer 1 — common/fetcher.js

Singleton HTTP client. All HTTP calls go through here — one place to add auth headers, token refresh, error handling, or request logging.

📄src/common/fetcher.js
class Fetcher {
    static instance = null;

    static getInstance() {
        if (!Fetcher.instance) {
            Fetcher.instance = new Fetcher();
        }
        return Fetcher.instance;
    }

    async sendRequest(url, options = {}) {
        const res = await fetch(url, {
            headers: { 'Content-Type': 'application/json', ...options.headers },
            ...options,
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
        const data = await res.json();
        return { data, status: res.status };
    }

    async getData(url)          { return this.sendRequest(url); }
    async postData(url, body)   { return this.sendRequest(url, { method: 'POST',   body: JSON.stringify(body) }); }
    async patchData(url, body)  { return this.sendRequest(url, { method: 'PATCH',  body: JSON.stringify(body) }); }
    async putData(url, body)    { return this.sendRequest(url, { method: 'PUT',    body: JSON.stringify(body) }); }
    async deleteData(url)       { return this.sendRequest(url, { method: 'DELETE' }); }
}

export const createFetcher = () => Fetcher.getInstance();

Layer 2 — repositories/items.js

One file per resource. Exports named functions that wrap the fetcher with endpoint-specific logic. Queries import these directly — IDE intellisense resolves every function.

📄src/repositories/items.js
import { createFetcher } from '@/common/fetcher';

const fetcher  = createFetcher();
const endpoint = '/api/items';

export async function getAllItems(params = {}) {
    const qs  = new URLSearchParams(params).toString();
    const url = qs ? `${endpoint}?${qs}` : endpoint;
    const response = await fetcher.getData(url);
    return response?.data;
}

export async function postItem(payload) {
    const response = await fetcher.postData(endpoint, payload);
    return response?.data;
}

export async function deleteItem(id) {
    const response = await fetcher.deleteData(`${endpoint}/${id}`);
    return response?.data;
}
💡To add a new resource: Create repositories/users.js with getAllUsers(), postUser(), etc. All share the same fetcher singleton.

Layer 3 — queries/itemsQueries.js

One file per feature. Hooks call the repository — never fetch() directly. Naming: use[Feature][Method]Query.

📄src/queries/itemsQueries.js
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { getAllItems, postItem, deleteItem } from '@/repositories/items';

// ─── GET ──────────────────────────────────────────────────────
export function useItemsGetQuery(params = {}, options = {}) {
    return useQuery({
        queryKey: ['itemsGetQuery', params],
        queryFn: () => getAllItems(params),
        staleTime: 0,
        gcTime: 0,
        refetchOnWindowFocus: false,
        refetchOnReconnect: false,
        retry: false,
        ...options,
    });
}

// ─── POST ─────────────────────────────────────────────────────
export function useItemsPostQuery() {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn: (newItem) => postItem(newItem),
        retry: false,
        onSuccess: () => {
            queryClient.invalidateQueries({ queryKey: ['itemsGetQuery'] });
        },
    });
}

// ─── DELETE ───────────────────────────────────────────────────
export function useItemsDeleteQuery() {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn: (id) => deleteItem(id),
        retry: false,
        onSuccess: () => {
            queryClient.invalidateQueries({ queryKey: ['itemsGetQuery'] });
        },
    });
}

Layer 4 — controller/ItemsController.jsx

Consumes query hooks, manages local state (search, pagination), handles events, and passes everything to a single child via Children.only(cloneElement(children, ...)).

📄src/controller/ItemsController.jsx
'use client';

import { Children, cloneElement, useEffect, useState } from 'react';
import {
    useItemsGetQuery,
    useItemsPostQuery,
    useItemsDeleteQuery,
} from '@/queries/itemsQueries';

export function ItemsController({ children, ...props }) {
    const [search, setSearch] = useState('');
    const [page, setPage]     = useState(1);

    const items      = useItemsGetQuery(
        { search, page: String(page), limit: '20' },
        { enabled: true }
    );
    const postToItems = useItemsPostQuery();
    const deleteItem  = useItemsDeleteQuery();

    useEffect(() => {
        if (postToItems.isSuccess) { setSearch(''); setPage(1); }
    }, [postToItems.isSuccess]);

    const handleCreate = (name) => postToItems.mutate({ name });
    const handleDelete = (id)   => deleteItem.mutate(id);
    const handleSearch = (value) => { setSearch(value); setPage(1); };

    return Children.only(
        cloneElement(children, {
            items, postToItems, deleteItem,
            page, search,
            onSearch: handleSearch,
            onPageChange: setPage,
            onCreate: handleCreate,
            onDelete: handleDelete,
            ...props,
        })
    );
}

Layer 5 — UI Component + Page

The UI component is pure — receives all data as props, renders JSX, no data logic. The page wires Controller + UI together.

📄src/app/items/page.jsx — the page
import { ItemsController } from '@/controller/ItemsController';
import AllItemsUI from '@/components/pages/items/AllItemsUI';

export default function ItemsPage(props) {
    return (
        <ItemsController {...props}>
            <AllItemsUI />
        </ItemsController>
    );
}
📄src/components/pages/items/AllItemsUI.jsx — the UI
export default function AllItemsUI({
    items,          // query object — items.data, items.isLoading, items.isError
    postToItems,    // mutation — postToItems.isPending
    deleteItem,     // mutation — deleteItem.isPending
    search, page,
    onSearch, onPageChange, onCreate, onDelete,
}) {
    return (
        <div>
            <input value={search} onChange={(e) => onSearch(e.target.value)} placeholder="Search…" />

            {items.isLoading && <p>Loading…</p>}
            {items.isError && <p>Error: {items.error.message}</p>}
            {items.data && (
                <ul>
                    {items.data.map((item) => (
                        <li key={item.id}>
                            {item.name}
                            <button onClick={() => onDelete(item.id)}>Delete</button>
                        </li>
                    ))}
                </ul>
            )}

            <button onClick={() => onCreate('New Item')} disabled={postToItems.isPending}>
                {postToItems.isPending ? 'Creating…' : '+ Add Item'}
            </button>
        </div>
    );
}

Adding a New Feature

Follow the same 5-layer pattern for every new resource:

✦
1. Repository — repositories/users.js — Users class with getAllUsers(), postUser(), deleteUser(). Uses the shared fetcher.
✦
2. Queries — queries/usersQueries.js — useUsersGetQuery, useUsersPostQuery, useUsersDeleteQuery. All hooks call the repository.
✦
3. Controller — controller/UsersController.jsx — consumes queries, manages state, Children.only(cloneElement(children, ...)).
✦
4. UI component — components/pages/users/AllUsersUI.jsx — pure component, receives query objects + handlers as props.
✦
5. Page — app/users/page.jsx — <UsersController><AllUsersUI /></UsersController>.

Key Concepts

queryKey

Unique array identifying cached data. Include filter params to scope: ['itemsGetQuery', { search }].

staleTime / gcTime

staleTime: how long before refetch is eligible. gcTime: how long unused cache survives. Both set to 0 by default.

invalidateQueries

Marks queries as stale after a mutation, triggering a background refetch to keep UI in sync.

Devtools

Floating panel (bottom-right) showing all active queries, cache status, and data. Click the TanStack logo to open.

Best Practices

✦
Fetcher is the single HTTP layer — All requests go through the fetcher singleton. Add auth headers, token refresh, or error handling in one place.
✦
One repository per resource — Items, Users, Teams — each gets its own class wrapping the fetcher with resource-specific endpoints.
✦
One queries file per feature — Group all hooks (GET, POST, DELETE) for a feature in one file — e.g. itemsQueries.js.
✦
Naming: use[Feature][Method]Query — useItemsGetQuery, useItemsPostQuery, useItemsDeleteQuery — consistent and discoverable.
✦
Queries never call fetch() directly — Hooks call the repository. The repository calls the fetcher. Clean separation.
✦
Controller owns the state — Search, filters, pagination — all live in the controller, never in UI components.
✦
Children.only + cloneElement — Controllers pass data to a single child via cloneElement — keeps them composable and testable.
✦
UI stays pure — No useQuery, no fetch, no side-effects inside presentational components. Only receive props and render.
🛠Open your scaffolded app and click the TanStack logo in the bottom-right corner to open the React Query Devtools. Inspect every query's cache, status, data, and trigger manual refetches.