React-Admin JSON Server Data Provider

Common errors

• TypeError: Cannot read properties of undefined (reading 'total')

  cause The `X-Total-Count` header is missing or inaccessible in the `getList` or `getManyReference` response, preventing `react-admin` from determining the total number of records.
  fix Verify that your backend sends the `X-Total-Count` header. If using a different domain for your API, ensure `Access-Control-Expose-Headers: X-Total-Count` is configured in your backend's CORS policy.

• CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause Your `react-admin` application is trying to access an API on a different domain without proper CORS headers configured on the server-side.
  fix Configure your backend server to include appropriate `Access-Control-Allow-Origin` headers (e.g., `Access-Control-Allow-Origin: *` for development, or specific origins in production) and `Access-Control-Expose-Headers` for `X-Total-Count`.

• React-admin displays 'No results found' even though the API returns data.

  cause This often happens when `react-admin` cannot parse the `X-Total-Count` header, leading it to believe there are zero records, or if the API response format does not exactly match expectations (e.g., `id` field name).
  fix Inspect network requests to confirm the `X-Total-Count` header is present and readable. Also, ensure your API's primary key field is named `id` as expected by default, or provide a custom `id` mapper if it's named differently.

Warnings

• breaking The `ra-data-json-server` provider requires the backend API to return an `X-Total-Count` header for `getList` and `getManyReference` calls. Without it, pagination and total record counts will not function correctly in `react-admin`.
  Fix: Configure your backend to include an `X-Total-Count` header in the response, e.g., `X-Total-Count: 319`. If your API is on a different domain, ensure `Access-Control-Expose-Headers: X-Total-Count` is set in your CORS policy.
• gotcha When developing with `ra-data-json-server` against a different origin API, browser security policies (CORS) might block access to custom headers like `X-Total-Count`. This will lead to pagination issues in `react-admin`.
  Fix: Ensure your backend includes the `Access-Control-Expose-Headers: X-Total-Count` header in its CORS policy to allow the browser to read the `X-Total-Count` response header.
• gotcha The `updateMany` and `deleteMany` operations are implemented as multiple individual `PUT` or `DELETE` requests, not a single batch request, matching JSON Server's default behavior. This can lead to performance overhead for large batch operations.
  Fix: For better performance on batch operations, consider creating a custom `httpClient` that intercepts and optimizes `updateMany`/`deleteMany` requests, or use a data provider designed for your specific backend that supports batch operations natively.
• gotcha Recent fixes indicate potential issues with `id` values of `0` in `useCreate` and stale nested field values in `SimpleFormIterator`. While these are fixed in 5.14.5, older versions might exhibit incorrect cache updates or form state behavior.
  Fix: Upgrade to `ra-data-json-server@5.14.5` or later to ensure proper handling of `id=0` and correct form state management for nested fields.

Install

• npm install ra-data-json-server npm
• yarn add ra-data-json-server yarn
• pnpm add ra-data-json-server pnpm

Imports

• jsonServerProvider
  wrong:

  import { jsonServerProvider } from 'ra-data-json-server';

  correct:

  import jsonServerProvider from 'ra-data-json-server';

  The primary data provider function is a default export.
• jsonServerProvider
  wrong:

  const jsonServerProvider = require('ra-data-json-server');

  correct:

  import jsonServerProvider from 'ra-data-json-server';

  While CommonJS `require` might technically work in some setups, `react-admin` and its ecosystem are primarily ESM-first. It's best to use ES module imports.
• httpClient configuration

  import { fetchUtils } from 'react-admin';
  const httpClient = (url, options = {}) => { /* ... */ return fetchUtils.fetchJson(url, options); };
  const dataProvider = jsonServerProvider('url', httpClient);

  Custom HTTP headers are added by wrapping `react-admin`'s `fetchUtils.fetchJson` and passing the custom client as the second argument to `jsonServerProvider`.

Quickstart

Initializes a `react-admin` application with `ra-data-json-server` connected to JSONPlaceholder, defining 'posts' and 'users' resources.

import * as React from 'react';
import { Admin, Resource } from 'react-admin';
import jsonServerProvider from 'ra-data-json-server';

// For demonstration purposes, we'll use a simple list component.
// In a real app, you'd define your own PostList.
const PostList = () => <div>Posts List (render your actual list here)</div>;

const App = () => (
    <Admin dataProvider={jsonServerProvider('https://jsonplaceholder.typicode.com')}>
        <Resource name="posts" list={PostList} />
        <Resource name="users" list={PostList} />
    </Admin>
);

export default App;