marmelab · ThieryMichel · Mar 31, 2026 · Nov 6, 2025 · Mar 10, 2026 · Mar 11, 2026
diff --git a/.agents/skills/i18n/SKILL.md b/.agents/skills/i18n/SKILL.md
diff --git a/Agents.md b/Agents.md
@@ -2,82 +2,26 @@
 
 React-admin is a comprehensive frontend framework for building B2B and admin applications on top of REST/GraphQL APIs, using TypeScript, React, and Material UI. It's an open-source project maintained by Marmelab that provides a complete solution for B2B applications with data-driven interfaces.
 
-## Architecture & Design Patterns
-
-### Key Principles
+## Design Principles
 
 - Designed for Single-Page Application (SPA) architecture
-- Provider-based abstraction for data fetching, auth, and i18n
-- "Batteries included but removable" - everything is replaceable
-- User Experience and Developer Experience are equally important
-- Backward compatibility prioritized over new features
-- Composition over Configuration - Use React patterns, not custom DSLs
-- Minimal API Surface - If it can be done in React, don't add to core
-- Standing on Giants' Shoulders - Use best-in-class libraries, don't reinvent the wheel
-
-### Provider Pattern
-
-React-admin uses adapters called "providers" for external integrations:
-
-```typescript
-// Data Provider - abstracts API calls
-dataProvider.getList('posts', {
-    pagination: { page: 1, perPage: 5 },
-    sort: { field: 'title', order: 'ASC' },
-    filter: { author_id: 12 }
-})
-
-// Auth Provider - handles authentication
-authProvider.checkAuth()
-authProvider.login({ username, password })
-authProvider.getPermissions()
-
-// i18n Provider - manages translations
-i18nProvider.translate('ra.action.save')
-```
-
-### Hook-Based API
-
-All functionality exposed through hooks following React patterns:
-
-```typescript
-// Data hooks
-const { data, isLoading } = useGetList('posts', {
-    pagination: { page: 1, perPage: 10 }
-});
-
-// State management hooks
-const [filters, setFilters] = useFilterState();
-const [page, setPage] = usePaginationState();
-
-// Auth hooks
-const { permissions } = usePermissions();
-const canAccess = useCanAccess({ resource: 'posts', action: 'edit' });
-```
-
-### Headless Core
-
-The `ra-core` package contains all logic without UI. UI components are in separate packages like `ra-ui-materialui`. This allows:
-
-- Custom UIs using core hooks and controllers
-- Swapping UI libraries without changing core logic
+- Backward compatibility over new features — avoid breaking changes
+- Minimal API surface — if it can be done in a few lines of React, don't add it to core
+- Provider pattern — data fetching, auth, and i18n are abstracted behind swappable provider adapters (`dataProvider`, `authProvider`, `i18nProvider`)
+- Headless core — `ra-core` contains all logic without UI; `ra-ui-materialui` provides the Material UI layer. This separation is intentional — don't couple logic to UI
+- Controller-view separation — controllers in `ra-core/src/controller/` expose business logic via hooks; views in `ra-ui-materialui/src/` handle rendering
+- Context: pull, don't push — components expose data to descendants via context + custom hooks, not prop drilling. Every component that fetches data or defines callbacks creates a context for it
+- `useEvent()` internal hook — use this for memoized event handlers instead of `useCallback`
 
-### Controller-View Separation
+## Anti-Patterns
 
-- Controllers in `ra-core/src/controller/` handle business logic
-- Views in `ra-ui-materialui/src/` handle rendering
-- Controllers provide data and callbacks via hooks
-
-### Context: Pull, Don’t Push
-
-Communication between components can be challenging, especially in large React applications, where passing props down several levels can become cumbersome. React-admin addresses this issue using a pull model, where components expose props to their descendants via a context, and descendants can consume these props using custom hooks.
-
-Whenever a react-admin component fetches data or defines a callback, it creates a context and places the data and callback in it.
+- No `React.cloneElement()` — it breaks composition
+- No children inspection — violates React patterns (exception: Datagrid)
+- No features achievable in pure React — keep the API surface small
+- No comments when code is self-explanatory
 
 ## Codebase Organization
 
-### Monorepo Structure
-
 ```
 react-admin/
 ├── packages/              # Lerna-managed packages
@@ -98,16 +42,7 @@ react-admin/
 └── scripts/             # Build scripts
 ```
 
-### Key ra-core Directories
-
-- `src/auth/` - Authentication and authorization (54 files)
-- `src/controller/` - CRUD controllers and state management
-- `src/dataProvider/` - Data fetching and caching logic (70 files)
-- `src/form/` - Form handling (31 files)
-- `src/routing/` - Navigation and routing (26 files)
-- `src/i18n/` - Internationalization (30 files)
-
-### Package Dependencies
+## Package Dependencies
 
 - **Core**: React 18.3+, TypeScript 5.8+, lodash 4.17+, inflection 3.0+
 - **Routing**: React Router 6.28+
@@ -116,190 +51,36 @@ react-admin/
 - **UI Components**: Material UI 5.16+
 - **Testing**: Jest 29.5+, Testing Library, Storybook, Cypress
 
-## Development Practices
-
-### TypeScript Requirements
-
-- **Strict mode enabled** - no implicit any
-- **Complete type exports** - all public APIs must be typed
-- **Generic types** for flexibility in data providers and resources
-- **JSDoc comments** for better IDE support
-
-```typescript
-// GOOD - Properly typed with generics
-export const useGetOne = <RecordType extends RaRecord = any>(
-    resource: string,
-    options?: UseGetOneOptions<RecordType>
-): UseGetOneResult<RecordType> => { ... }
-
-// BAD - Using any without constraint
-export const useGetOne = (resource: any, options?: any): any => { ... }
-```
-
-### Component Patterns
-
-1. **Composition over configuration** - Use React composition patterns
-2. **Smart defaults** - Components should work out-of-the-box
-3. **Controlled and uncontrolled** modes supported
-4. **Props pass-through** - Spread additional props to root element
-
-```jsx
-// Component composition example
-export const MyField = ({ source, ...props }) => {
-    const record = useRecordContext();
-    return (
-        <TextField
-            {...props}  // Pass through all additional props
-            value={record?.[source]}
-        />
-    );
-};
-```
-
-### File Organization
-- **Feature-based structure** within packages (not type-based)
-- **Co-location** - Tests (`.spec.tsx`) and stories (`.stories.tsx`) next to components
-- **Index exports** - Each directory has an index.ts exporting public API
-- **Flat structure** within features - avoid unnecessary nesting
-
-### Documentation
-
-Every new feature or API change must be documented. The documentation consists of Markdown files located in the `/docs/` directory and built with Jekyll, one file per component or hook.
-
-All documentation files must include:
-
-- A brief description of the component or hook
-- Usage examples
-- List of props or parameters (required props first, then in alphabetical order)
-- Detailed usage for each prop/parameter (in alphabetical order)
-- Recipes and advanced usage examples if applicable
-
-Headless hooks and components (the ones in `ra-core`) are also documented in the `/docs_headless/` directory.
-
-### Pre-commit Hooks
-
-- Automatic test execution for modified files
-- Prettier formatting check
-- ESLint validation
-- TypeScript compilation
+## Testing
 
+All changes must include tests.
 
-### Development Workflow
-```bash
-# Initial setup
-make install         # Install all dependencies
-
-# After making changes
-make build           # Build packages (TypeScript compilation)
-make test            # run unit and e2e tests
-
-# Before pushing changes
-make lint           # Check code quality
-make prettier       # Format code
-```
+- Stories: every component needs `*.stories.tsx` covering all props. Use FakeRest for mock data. Make data realistic — stories are used for screenshots and visual testing
+- Unit/integration tests: `*.spec.tsx` files should reuse the component's stories as test cases. Assert on user-visible output (text, interactions), not implementation details or HTML attributes
+- E2E (Cypress): kept minimal, targeting `examples/simple/`. Only for critical user paths
 
-### Pull Request Process
+## Documentation
 
-1. **Target branch**: `next` for features, `master` for bug fixes or documentation changes
-2. **Required checks**:
-   - All tests passing (`make test`)
-   - Linting clean (`make lint`)
-   - Prettier formatted (`make prettier`)
-   - TypeScript compiles (`yarn typecheck`)
+Every new feature or API change must be documented.
 
-3. **Commit Messages**: Clear, descriptive messages focusing on "why"
-   ```
-   fix: Prevent duplicate API calls in useGetList hook
-   feat: Add support for custom row actions in Datagrid
-   docs: Clarify dataProvider response format
-   ```
-
-4. **Documentation**: Update relevant docs for API changes
-5. **Title**: Start with a verb (Add / Fix / Update / Remove), prefix with `[Doc]` or `[TypeScript]` if the change only concerns doc or types. 
-
-### Common Make Commands
-```bash
-make                # Show all available commands
-make install        # Install dependencies
-make build          # Build all packages (CJS + ESM)
-make test           # Run all tests
-make lint           # Check code quality
-make prettier       # Format code
-make run-simple     # Run simple example
-make run-demo       # Run demo application
-```
+- `/docs/` (Jekyll) — one Markdown file per component or hook. Each file must include: description, usage examples, props/parameters list (required first, then alphabetical), detailed usage per prop, and recipes if applicable
+- `/docs_headless/` (Astro + Starlight) — documents headless hooks and components from `ra-core`
 
-### Performance Considerations
+## Pull Requests
 
-- Use `React.memo()` for expensive components
-- Leverage `useMemo()` and `useCallback()` appropriately
-- Use `useEvent()` (an internal hook) for memoized event handlers
-- Implement pagination for large datasets
-- Use query caching via React Query
-
-### Accessibility
-
-- Follow WCAG guidelines
-- Ensure keyboard navigation works
-- Provide proper ARIA labels
-- Test with screen readers
-
-### Browser Support
-- Modern browsers only (Chrome, Firefox, Safari, Edge)
-- No IE11 support
-- ES5 compilation target for compatibility
-
-## Misc
-
-- **Don't use `React.cloneElement()`** - it breaks composition
-- **Don't inspect children** - violates React patterns (exception: Datagrid)
-- **Don't add comments** when code is self-explanatory 
-- **Don't add features** achievable in a few lines with pure React
-- **Don't skip tests** - they run automatically on commit
-- **Don't force push** to main/master branches
-
-## Testing Requirements
-
-All developments must include tests to ensure code quality and prevent regressions.
-
-### Storybook
-
-- **Location**: Stories alongside components as `*.stories.tsx`
-- **Coverage**: All components must have stories demonstrating usage for all props
-- **Mocking**: Use jest mocks sparingly, prefer integration tests
-- **Data**: Use mock data providers (e.g., FakeRest) for stories. Make realistic data scenarios as the stories are also used for screenshots and visual testing.
-
-### Unit & Integration Testing (Jest)
-
-- **Location**: Tests alongside source files as `*.spec.tsx`
-- **Test Cases**: Reuse the component's stories as test cases
-- **Assertions**: Use testing-library to render and assert on elements. Don't test implementation details or HTML attributes, use assertions based on user interactions and visible output. 
-- **Commands**:
-  ```bash
-  make test-unit         # Run all unit and functional tests
-  npx jest [pattern]     # Run specific tests
+- Target branch: `next` for features, `master` for bug fixes or documentation
+- Title: start with a verb (Add / Fix / Update / Remove). Prefix with `[Doc]` or `[TypeScript]` if the change only concerns docs or types
+- Commit messages: conventional commits focusing on "why"
   ```
-
-### E2E Testing (Cypress)
-
-Kept minimal to critical user paths due to maintenance overhead.
-
-- **Location**: `cypress/` directory
-- **Target**: Simple example app (`examples/simple/`)
-- **Coverage**: Critical user paths and interactions
-- **Commands**:
-
-  ```bash
-  make test-e2e          # Run in CI mode
-  # or for local testing with GUI:
-  make run-simple        # Start test app with vite
-  make test-e2e-local    # Run e2e tests with GUI
+  fix: Prevent duplicate API calls in useGetList hook
+  feat: Add support for custom row actions in Datagrid
+  docs: Clarify dataProvider response format
   ```
 
-### Static Analysis
+## Static Analysis
 
 ```bash
 make lint               # ESLint checks
+make typecheck          # TypeScript type checking
 make prettier           # Prettier formatting
-make build              # TypeScript type checking
 ```
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,28 @@
 # Changelog
 
+## 5.14.5
+
+* Add ArrayFieldBase component ([#11191](https://github.com/marmelab/react-admin/pull/11191)) ([WiXSL](https://github.com/WiXSL))
+* [Fix] Prevent stale nested field values when re-adding items in SimpleFormIterator ([#11201](https://github.com/marmelab/react-admin/pull/11201)) ([WiXSL](https://github.com/WiXSL))
+* Fix `useCreate` fails to update the cache when `id` equals 0 ([#11199](https://github.com/marmelab/react-admin/pull/11199)) ([ThieryMichel](https://github.com/ThieryMichel))
+* Fix mutation hooks types ([#11024](https://github.com/marmelab/react-admin/pull/11024)) ([djhi](https://github.com/djhi))
+* [Doc] Add ArrayFieldBase headless documentation ([#11192](https://github.com/marmelab/react-admin/pull/11192)) ([WiXSL](https://github.com/WiXSL))
+* [chore] Fix headless docs build ([#11188](https://github.com/marmelab/react-admin/pull/11188)) ([slax57](https://github.com/slax57))
+* Bump path-to-regexp from 0.1.12 to 0.1.13 ([#11210](https://github.com/marmelab/react-admin/pull/11210)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump handlebars from 4.7.7 to 4.7.9 ([#11206](https://github.com/marmelab/react-admin/pull/11206)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump astro from 5.15.9 to 5.18.1 ([#11205](https://github.com/marmelab/react-admin/pull/11205)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump picomatch from 2.3.1 to 2.3.2 ([#11203](https://github.com/marmelab/react-admin/pull/11203)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump smol-toml from 1.5.2 to 1.6.1 ([#11202](https://github.com/marmelab/react-admin/pull/11202)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump flatted from 3.3.3 to 3.4.2 ([#11197](https://github.com/marmelab/react-admin/pull/11197)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump h3 from 1.15.8 to 1.15.9 ([#11196](https://github.com/marmelab/react-admin/pull/11196)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump h3 from 1.15.5 to 1.15.8 ([#11194](https://github.com/marmelab/react-admin/pull/11194)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Bump devalue from 5.6.3 to 5.6.4 ([#11189](https://github.com/marmelab/react-admin/pull/11189)) ([dependabot[bot]](https://github.com/apps/dependabot))
+* Fix tar security alerts ([#11215](https://github.com/marmelab/react-admin/pull/11215)) ([WiXSL](https://github.com/WiXSL))
+* Fix markdown-it security alert ([#11214](https://github.com/marmelab/react-admin/pull/11214)) ([WiXSL](https://github.com/WiXSL))
+* Fix minimatch security alerts ([#11213](https://github.com/marmelab/react-admin/pull/11213)) ([WiXSL](https://github.com/WiXSL))
+* Fix ejs dependabot alert ([#11211](https://github.com/marmelab/react-admin/pull/11211)) ([WiXSL](https://github.com/WiXSL))
+* Fix picomatch dependabot alert ([#11212](https://github.com/marmelab/react-admin/pull/11212)) ([WiXSL](https://github.com/WiXSL))
+
 ## 5.14.4
 
 * Fix SavedQuery when `disableSyncWithLocation` is set ([#11173](https://github.com/marmelab/react-admin/pull/11173)) ([ThieryMichel](https://github.com/ThieryMichel))

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@Agents.md
diff --git a/Makefile b/Makefile
@@ -131,6 +131,9 @@ update-package-exports: ## Update the package.json "exports" field for all packa
 
 build: build-ra-core build-ra-router-tanstack build-ra-data-fakerest build-ra-ui-materialui build-ra-data-json-server build-ra-data-local-forage build-ra-data-local-storage build-ra-data-simple-rest build-ra-data-graphql build-ra-data-graphql-simple build-ra-input-rich-text build-data-generator build-ra-language-english build-ra-language-french build-ra-i18n-i18next build-ra-i18n-polyglot build-react-admin build-ra-no-code build-create-react-admin update-package-exports  ## compile ES6 files to JS
 
+typecheck: ## check TypeScript types
+	@yarn typecheck
+
 doc: ## compile doc as html and launch doc web server
 	@yarn doc
 

diff --git a/docs/ArrayField.md b/docs/ArrayField.md
@@ -12,6 +12,8 @@ storybook_path: ra-ui-materialui-fields-arrayfield--basic
 
 `<ArrayField>` creates a [`ListContext`](./useListContext.md) with the field value, and renders its children components - usually iterator components like [`<DataTable>`](./DataTable.md) or [`<SingleFieldList>`](./SingleFieldList.md).
 
+`<ArrayField>` is the Material UI export of the headless [`<ArrayFieldBase>`](https://marmelab.com/ra-core/arrayfieldbase/) component from `ra-core`.
+
 ## Usage
 
 `<ArrayField>` is ideal for collections of objects, e.g. `tags` and `backlinks` in the following `post` object:

diff --git a/docs/Translation.md b/docs/Translation.md
@@ -340,4 +340,14 @@ The following components take advantage of browser localization:
 - [`<DateRangeInput>`](./DateRangeInput.md)
 - [ `<NumberField>`](./NumberField.md)
 - [`<NumberInput>`](./NumberInput.md)
-- [`<TimeInput>`](./TimeInput.md)
+- [`<TimeInput>`](./TimeInput.md)
+
+## Agent Skill
+
+React-admin provides a specialized agent skill to help you translate your application. Install it in your repository with the [`skills`](https://skills.sh/) command:
+
+```bash
+npx skills add marmelab/react-admin --skill i18n
+```
+
+This works with OpenCode, Claude Code, Codex, Cursor, and many more.