Skip to content

Commit 43d82de

Browse files
slax57slax57
authored
Merge pull request #11158 from marmelab/doc-coding-agent
[Doc] Add react-admin Skill and AI coding assistant instructions
2 parents 8c62408 + 2384064 commit 43d82de

3 files changed

Lines changed: 270 additions & 1 deletion

File tree

‎.agents/skills/react-admin/SKILL.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
name: react-admin
3+
description: This skill should be used when building, modifying, or debugging a react-admin application — including creating resources, lists, forms, data fetching, authentication, relationships between entities, custom pages, or any CRUD admin interface built with react-admin.
4+
---
5+
6+
# React-Admin Development Guide
7+
8+
React-admin is a framework for building single-page applications on top of REST/GraphQL APIs. It builds on top of React Query, react-hook-form, react-router, and Material UI. It provides 150+ components and dozens of hooks. Before writing custom code, always check if react-admin already provides a component or hook for the task. Full documentation: https://marmelab.com/react-admin/doc/
9+
10+
## Providers (Backend Abstraction)
11+
12+
React-admin never calls APIs directly. All communication goes through **providers** — adapters that translate react-admin's standardized calls into API-specific requests. The three main providers are:
13+
14+
- **dataProvider**: All CRUD operations (`getList`, `getOne`, `create`, `update`, `delete`, `getMany`, `getManyReference`, `updateMany`, `deleteMany`). See [DataProviders](https://marmelab.com/react-admin/DataProviders.html) and [50+ existing adapters](https://marmelab.com/react-admin/DataProviderList.html).
15+
- **authProvider**: Authentication and authorization. See [Authentication](https://marmelab.com/react-admin/Authentication.html).
16+
- **i18nProvider**: Translations (`translate`, `changeLocale`, `getLocale`).
17+
18+
**Critical rule**: Never use `fetch`, `axios`, or direct HTTP calls in components. Always use data provider hooks. This ensures proper caching, loading states, error handling, authentication, and optimistic rendering.
19+
20+
## Composition (Not God Components)
21+
22+
React-admin uses composition over configuration. Override behavior by passing child components, not by setting dozens of props:
23+
24+
```jsx
25+
<Edit actions={<MyCustomActions />}>
26+
<SimpleForm>
27+
<TextInput source="title" />
28+
</SimpleForm>
29+
</Edit>
30+
```
31+
32+
To customize the layout, pass a custom layout component to `<Admin layout={MyLayout}>`. To customize the menu, pass it to `<Layout menu={MyMenu}>`. This chaining is by design — see [Architecture](https://marmelab.com/react-admin/Architecture.html).
33+
34+
## Context: Pull, Don't Push
35+
36+
React-admin components expose data to descendants via React contexts. Access data using hooks rather than passing props down:
37+
38+
- `useRecordContext()` — current record in Show/Edit/Create views. See [useRecordContext](https://marmelab.com/react-admin/useRecordContext.html).
39+
- `useListContext()` — list data, filters, pagination, sort in List views. See [useListContext](https://marmelab.com/react-admin/useListContext.html).
40+
- `useShowContext()`, `useEditContext()`, `useCreateContext()` — page-level state for detail views.
41+
- `useTranslate()` — translation function from i18nProvider.
42+
- `useGetIdentity()` — current user from authProvider.
43+
44+
## Hooks Over Custom Components
45+
46+
When a react-admin component's UI doesn't fit, use the underlying hook instead of building from scratch. Controller hooks (named `use*Controller`) provide all the logic without the UI:
47+
48+
- `useListController()` — list fetching, filtering, pagination logic
49+
- `useEditController()` — edit form fetching and submission logic
50+
- `useShowController()` — show page data fetching logic
51+
52+
## Routing
53+
54+
`<Resource>` declares CRUD routes automatically (`/posts`, `/posts/create`, `/posts/:id/edit`, `/posts/:id/show`). Use `<CustomRoutes>` for non-CRUD pages. Use `useCreatePath()` to build resource URLs and `<Link>` from react-admin for navigation. Default router is react-router (HashRouter), but TanStack Router is also supported via `routerProvider`. See [Routing](https://marmelab.com/react-admin/Routing.html).
55+
56+
## Data Fetching
57+
58+
### Query Hooks (Reading Data)
59+
60+
```jsx
61+
const { data, total, isPending, error } = useGetList('posts', {
62+
pagination: { page: 1, perPage: 25 },
63+
sort: { field: 'created_at', order: 'DESC' },
64+
filter: { status: 'published' },
65+
});
66+
67+
const { data: record, isPending } = useGetOne('posts', { id: 123 });
68+
const { data: records } = useGetMany('posts', { ids: [1, 2, 3] });
69+
const { data, total } = useGetManyReference('comments', {
70+
target: 'post_id', id: 123,
71+
pagination: { page: 1, perPage: 25 },
72+
});
73+
```
74+
75+
See [useGetList](https://marmelab.com/react-admin/useGetList.html), [useGetOne](https://marmelab.com/react-admin/useGetOne.html).
76+
77+
### Mutation Hooks (Writing Data)
78+
79+
All mutations return `[mutate, state]`. They support three **mutation modes**:
80+
81+
- **pessimistic** (default): Wait for server response, then update UI.
82+
- **optimistic**: Update UI immediately, revert on server error.
83+
- **undoable**: Update UI, show undo notification, commit after delay.
84+
85+
```jsx
86+
const [create, { isPending }] = useCreate();
87+
const [update] = useUpdate();
88+
const [deleteOne] = useDelete();
89+
90+
// Call with resource and params
91+
create('posts', { data: { title: 'Hello' } });
92+
update('posts', { id: 1, data: { title: 'Updated' }, previousData: record });
93+
deleteOne('posts', { id: 1, previousData: record });
94+
```
95+
96+
Pass `mutationMode: 'optimistic'` or `'undoable'` for instant UI feedback. See [useCreate](https://marmelab.com/react-admin/useCreate.html), [useUpdate](https://marmelab.com/react-admin/useUpdate.html).
97+
98+
## Authentication & Authorization
99+
100+
```typescript
101+
const authProvider = {
102+
login: ({ username, password }) => Promise<void>,
103+
logout: () => Promise<void>,
104+
checkAuth: () => Promise<void>, // Verify credentials are valid
105+
checkError: (error) => Promise<void>, // Detect auth errors from API responses
106+
getIdentity: () => Promise<{ id, fullName, avatar }>,
107+
getPermissions: () => Promise<any>,
108+
canAccess: ({ resource, action, record }) => Promise<boolean>, // RBAC
109+
};
110+
```
111+
112+
Each auth provider method has a corresponding hook (e.g. `useGetIdentity()`, `useCanAccess()`).
113+
114+
- **Custom routes are public by default.** Wrap them with `<Authenticated>` or call `useAuthenticated()` to require login. See [Authenticated](https://marmelab.com/react-admin/Authenticated.html).
115+
- Centralize authorization in `authProvider.canAccess()`, not in individual components. Use `useCanAccess()` to check permissions. See [useCanAccess](https://marmelab.com/react-admin/useCanAccess.html) and [AuthRBAC](https://marmelab.com/react-admin/AuthRBAC.html).
116+
- The dataProvider must include credentials (Bearer token, cookies) in requests — authProvider handles login, but dataProvider handles API calls. Configure `httpClient` in data provider setup.
117+
118+
## Relationships Between Entities
119+
120+
Fetching all the data (including relationships) upfront for a given page is an anti-pattern. Instead, fetch related records on demand using reference fields and inputs.
121+
122+
### Displaying Related Records (Fields)
123+
124+
```jsx
125+
{/* Show a the company of the current record based on its company_id */}
126+
<ReferenceField source="company_id" reference="companies" />
127+
128+
{/* Show a list of related records (reverse FK) */}
129+
<ReferenceManyField reference="comments" target="post_id">
130+
<DataTable>
131+
<TextField source="body" />
132+
<DateField source="created_at" />
133+
</DataTable>
134+
</ReferenceManyField>
135+
136+
{/* Show multiple referenced records (array of IDs) */}
137+
<ReferenceArrayField source="tag_ids" reference="tags">
138+
<SingleFieldList>
139+
<ChipField source="name" />
140+
</SingleFieldList>
141+
</ReferenceArrayField>
142+
```
143+
144+
See [ReferenceField](https://marmelab.com/react-admin/ReferenceField.html), [ReferenceManyField](https://marmelab.com/react-admin/ReferenceManyField.html), [ReferenceArrayField](https://marmelab.com/react-admin/ReferenceArrayField.html).
145+
146+
### Editing Related Records (Inputs)
147+
148+
```jsx
149+
{/* Select from another resource (FK) */}
150+
<ReferenceInput source="company_id" reference="companies" />
151+
152+
{/* Multi-select from another resource (array of IDs) */}
153+
<ReferenceArrayInput source="tag_ids" reference="tags" />
154+
```
155+
156+
See [ReferenceInput](https://marmelab.com/react-admin/ReferenceInput.html), [ReferenceArrayInput](https://marmelab.com/react-admin/ReferenceArrayInput.html).
157+
158+
## Forms
159+
160+
React-admin forms are built on react-hook-form. Use `<SimpleForm>` for single-column layouts and `<TabbedForm>` for multi-tab layouts. See [SimpleForm](https://marmelab.com/react-admin/SimpleForm.html), [TabbedForm](https://marmelab.com/react-admin/TabbedForm.html).
161+
162+
Pass validators to input components: `required()`, `minLength(min)`, `maxLength(max)`, `minValue(min)`, `maxValue(max)`, `number()`, `email()`, `regex(pattern, message)`, or a custom function returning an error string.
163+
164+
```jsx
165+
<TextInput source="title" validate={[required(), minLength(3)]} />
166+
```
167+
168+
Use RHF's `useWatch()` to create dynamic forms that react to field values:
169+
170+
## Resource Definition
171+
172+
Encapsulate resource components in index files for clean imports:
173+
174+
```jsx
175+
// posts/index.ts
176+
export default {
177+
list: PostList,
178+
create: PostCreate,
179+
edit: PostEdit,
180+
icon: PostIcon,
181+
recordRepresentation: (record) => record.title, // How records appear in references
182+
};
183+
```
184+
185+
See [Resource](https://marmelab.com/react-admin/Resource.html), [RecordRepresentation](https://marmelab.com/react-admin/RecordRepresentation.html).
186+
187+
## Custom Data Provider Methods
188+
189+
Extend the dataProvider with domain-specific methods:
190+
191+
```jsx
192+
const dataProvider = {
193+
...baseDataProvider,
194+
archivePost: async (id) => { /* custom logic */ },
195+
};
196+
// Call via useDataProvider and useQuery:
197+
// const dp = useDataProvider();
198+
// const { data } = useQuery(['archivePost', id], () => dp.archivePost(id));
199+
```
200+
201+
## Persistent Client State (Store)
202+
203+
Use `useStore()` for persistent user preferences (theme, column visibility, saved filters):
204+
205+
```jsx
206+
const [theme, setTheme] = useStore('theme', 'light');
207+
```
208+
209+
See [Store](https://marmelab.com/react-admin/Store.html).
210+
211+
## Notification, Redirect, Refresh
212+
213+
```jsx
214+
const notify = useNotify();
215+
const redirect = useRedirect();
216+
const refresh = useRefresh();
217+
218+
notify('Record saved', { type: 'success' });
219+
redirect('list', 'posts'); // Navigate to /posts
220+
redirect('edit', 'posts', 123); // Navigate to /posts/123
221+
refresh(); // Invalidate all queries
222+
```
223+
224+
## Deprecations
225+
226+
- Use DataTable instead of Datagrid
227+
- Prefer `<CanAccess>` and `useCanAccess` for authorization checks

‎docs/CodingAgents.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
layout: default
3+
title: "Using Coding Agents"
4+
---
5+
6+
# Using Coding Agents
7+
8+
AI coding assistants like Claude Code, GitHub Copilot, Cursor, Gemini CLI or Codex already know react-admin—they’ve been trained on it. But if you want high‑quality react-admin code (idiomatic, maintainable, and aligned with best practices), you need to guide them.
9+
10+
This page explains how to make your coding agent significantly better at writing react-admin applications.
11+
12+
## React-Admin Documentation on Context7
13+
14+
When an agent needs precise information about a hook or component API, give it direct access to the react-admin documentation via [Context7](https://github.com/upstash/context7#installation).
15+
16+
After installing the Context7 MCP server, reference Context7 and [`/marmelab/react-admin`](https://context7.com/marmelab/react-admin) directly in your prompt. For example:
17+
18+
```txt
19+
Add a form field to edit the author of the post.
20+
use context7 with /marmelab/react-admin
21+
```
22+
23+
This ensures the agent relies on the official docs instead of guessing.
24+
25+
## React-Admin Skill
26+
27+
You can go one step further by adding the official react-admin [skill](https://agentskills.io/):
28+
29+
[react-admin/SKILL.md](https://github.com/marmelab/react-admin/blob/master/.agents/skills/react-admin/SKILL.md)
30+
31+
Follow your agent’s instructions to install the skill in your repository (for example, `.claude/skills/react-admin/SKILL.md` for Claude Code).
32+
33+
Once installed, the agent will automatically apply react-admin best practices when generating code.
34+
35+
For example:
36+
37+
```
38+
In the company detail view, show the list of the contacts of the company.
39+
```
40+
41+
With the skill enabled, the agent will correctly choose `<ReferenceManyField>` and `<DataTable>` to display the related contacts.

‎docs/navigation.html‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,9 @@
1515
<li {% if page.path == 'NextJs.md' %} class="active" {% endif %}><a class="nav-link" href="./NextJs.html">Next.js</a></li>
1616
<li {% if page.path == 'Remix.md' %} class="active" {% endif %}><a class="nav-link" href="./Remix.html">Remix</a></li>
1717
<li {% if page.path == 'ReactRouterFramework.md' %} class="active" {% endif %}><a class="nav-link" href="./ReactRouterFramework.html">React Router Framework</a></li>
18-
<li {% if page.path == 'Deploy.md' %} class="active beginner" {% endif %}><a class="nav-link" href="./Deploy.html">Deployment</a></li>
1918
<li {% if page.path == 'TanStackStart.md' %} class="active" {% endif %}><a class="nav-link" href="./TanStackStart.html">TanStack Start</a></li>
19+
<li {% if page.path == 'Deploy.md' %} class="active beginner" {% endif %}><a class="nav-link" href="./Deploy.html">Deployment</a></li>
20+
<li {% if page.path == 'CodingAgents.md' %} class="active beginner" {% endif %}><a class="nav-link" href="./CodingAgents.html">Coding Agents</a></li>
2021
</ul>
2122

2223
<ul><div>Guides & Concepts</div>

0 commit comments

Comments
 (0)