React-admin framework: обзор и первые шаги для CRUD-панели

React-admin framework я беру, когда нужно за пару дней собрать рабочую CRUD-панель поверх готового REST- или GraphQL-API, а не тратить неделю на ручную вёрстку таблиц, форм и пагинации. Это библиотека для React, которая закрывает рутину любой админки: список записей с фильтрами и сортировкой, страницы просмотра, создание и редактирование, авторизацию и разграничение прав. Ты описываешь, какие есть сущности и откуда брать данные, - а фреймворк рисует интерфейс на Material UI. На реальных проектах, где заказчику нужна панель управления заказами поверх WooCommerce или собственного бэкенда на Laravel, это экономит десятки часов.

Дальше разберу, из чего складывается такая панель, как подружить её с любым API и с чего начать первый прототип. Без теории ради теории - только то, что использую в работе.

Что такое react-admin и зачем он мне на проектах

React-admin - это не конструктор с визуальным редактором, а набор React-компонентов и хуков. Ключевая идея: интерфейс отделён от источника данных. Между ними стоит слой Data Provider - объект с методами getList, getOne, create, update, delete. Фреймворку всё равно, что за бэкенд: PostgreSQL через REST, Firebase, GraphQL или даже REST API WordPress. Меняешь провайдер - остальной код панели остаётся прежним.

Я беру его в трёх типовых ситуациях. Первая - внутренняя админка для бизнеса: менеджер видит заказы, меняет статусы, выгружает данные. Вторая - панель поверх интернет-магазина, когда стандартной админки WooCommerce не хватает и нужен свой экран с логикой под конкретный склад и доставку СДЭК. Третья - быстрый MVP для стартапа, где важно за неделю показать работающий продукт инвестору, а не идеальную архитектуру.

Что react-admin даёт из коробки:

• списки с серверной пагинацией, сортировкой и фильтрами;
• формы создания и редактирования с валидацией;
• оптимистичные обновления - интерфейс реагирует мгновенно, откат при ошибке сервера;
• роли и права доступа через Auth Provider;
• тёмную тему, i18n и адаптив под мобильные без дополнительных плясок.

Из чего собирается админ-панель на React

Вся структура держится на трёх компонентах: <Admin>, <Resource> и представлениях (List, Edit, Create, Show). <Admin> - корень приложения, ему передают Data Provider и, при необходимости, Auth Provider. Внутри объявляешь ресурсы - по одному на каждую сущность API: заказы, клиенты, товары.

<Resource name="orders"> связывает URL-путь, имя эндпоинта и набор экранов. Дальше для каждого ресурса ты либо подключаешь автогенераторы (ListGuesser, EditGuesser), которые сами угадывают поля по ответу сервера, либо пишешь свои компоненты со строгим контролем над колонками и полями формы.

На старте я почти всегда начинаю с гессеров - они за минуту показывают, что API вообще отдаёт, и печатают в консоль готовый код компонента, который потом остаётся допилить. Это ускоряет прототип: не гадаешь, как называется поле, а сразу видишь черновик таблицы.

Data Provider: как подключить свой бэкенд

Самая частая точка, где новички спотыкаются, - соответствие формата API тому, что ждёт фреймворк. Для типового REST есть готовый пакет ra-data-simple-rest. Он рассчитывает, что список приходит массивом, а общее число записей сервер отдаёт в заголовке Content-Range. Если бэкенд отдаёт данные иначе (например, обёрнутыми в { data, total }), берёшь ra-data-json-server или пишешь тонкую обёртку - это буквально функция, которая транслирует вызовы фреймворка в твои запросы.

Установка и минимальный каркас выглядят так:

npm install react-admin ra-data-simple-rest

import { Admin, Resource, ListGuesser, EditGuesser } from 'react-admin';
import simpleRestProvider from 'ra-data-simple-rest';

const dataProvider = simpleRestProvider('https://api.example.com');

export const App = () => (
  <Admin dataProvider={dataProvider}>
    <Resource name="orders" list={ListGuesser} edit={EditGuesser} />
    <Resource name="customers" list={ListGuesser} />
  </Admin>
);

Этих 12 строк достаточно, чтобы получить рабочую панель с двумя разделами, пагинацией и формами. Если API требует токен, оборачиваешь fetch в httpClient и добавляешь заголовок Authorization - фреймворк принимает кастомный http-клиент вторым аргументом провайдера.

На практике при интеграции с эквайрингом T‑Bank или бэкендом магазина я почти никогда не использую голый simpleRest - пишу свою прослойку, которая перекладывает фильтры react-admin в query-параметры конкретного API и подставляет постраничные лимиты так, как ждёт сервер. Это 40-60 строк кода один раз, зато дальше все ресурсы работают единообразно.

Первые шаги: минимальная CRUD-панель за вечер

Когда каркас поднят, гессеры пора менять на явные компоненты - так ты контролируешь колонки, форматирование сумм и дат. Вот как выглядит осмысленный список заказов вместо автогенерации:

import { List, Datagrid, TextField, NumberField, DateField, EditButton } from 'react-admin';

export const OrderList = () => (
  <List>
    <Datagrid>
      <TextField source="id" />
      <TextField source="customer" />
      <NumberField source="total" options={{ style: 'currency', currency: 'RUB' }} />
      <DateField source="createdAt" showTime />
      <EditButton />
    </Datagrid>
  </List>
);

Дальше подключаешь этот компонент в ресурс через list={OrderList}, добавляешь форму Edit с полями <TextInput> и <SelectInput> для статуса - и полноценный CRUD готов. По моему опыту, базовая панель на 3-5 сущностей с фильтрами и ролями поднимается за один плотный вечер, если API уже есть. Львиная доля времени уходит не на react-admin, а на согласование форматов данных с бэкендом.

Порядок, которого я держусь на первом прогоне:

1. поднять <Admin> с одним ресурсом и гессером, проверить, что данные вообще приходят;
2. прикрутить авторизацию, пока не забыл про безопасность;
3. заменить гессеры на явные List/Edit по одному ресурсу за раз;
4. добавить фильтры и кастомные действия (смена статуса, экспорт в CSV);
5. прогнать сценарии менеджера руками - создать, изменить, удалить запись.

Если нужна не учебная заготовка, а панель под боевой процесс с интеграциями и правами, я обычно закладываю на разработку админ-панели на React под конкретные бизнес-процессы отдельный этап: свой Data Provider, кастомные экраны и связку с CRM.

React-admin против других фреймворков для админок

Выбор инструмента зависит от того, есть ли готовый бэкенд и насколько глубокая нужна кастомизация. Сравню то, с чем сам работал или что рассматривал под задачи клиентов:

React-admin выигрывает, когда сущностей много и они однотипные: описал ресурсы - получил десяток экранов бесплатно по трудозатратам. Как только логика становится нетиповой (сложные мастера, дашборды с графиками поверх таблиц), часть экранов всё равно пишешь руками, и тут я иногда смотрю в сторону Vue.js для отдельного BI-дашборда, а react-admin оставляю на CRUD-часть.

Аутентификация, права и подводные камни

Auth Provider - второй обязательный кирпич для боевой панели. Это объект с методами login, logout, checkAuth, checkError и getPermissions. Через getPermissions раздаёшь роли: менеджер видит заказы, но не трогает пользователей; админ видит всё. Фреймворк сам прячет кнопки и разделы по возвращённым правам - но серверную проверку это не заменяет, права на бэкенде всё равно нужны.

Грабли, на которые я наступал и о которых предупреждаю клиентов:

• Content-Range. Без этого заголовка пагинация ломается молча - список показывает первую страницу и не даёт листать. Настраивай CORS так, чтобы заголовок был доступен фронту.
• Формат идентификаторов. React-admin ждёт поле id. Если у тебя _id или uuid, маппинг делаешь в провайдере, иначе строки не редактируются.
• Тяжёлые связи. <ReferenceField> удобен, но на больших списках плодит лишние запросы. Кэшируй справочники или отдавай их встроенными в ответ.
• Кастомные действия. Смена статуса заказа, отправка в СДЭК, пуш в Telegram-бота на aiogram - всё это делается через useDataProvider и кастомные кнопки, но требует ручного кода поверх стандартных экранов.

По срокам и деньгам ориентир такой: полноценную CRM или админ-панель на React с интеграциями, ролями и кастомными экранами я делаю от 100 000 ₽. На рынке студии и фрилансеры за похожую панель просят очень по-разному, от 50 000 до 250 000 ₽ в зависимости от числа сущностей и интеграций, - это рыночный ориентир, а не мой прайс. Голый прототип на гессерах поверх готового API поднимается заметно быстрее и дешевле, но в продакшн такое почти никогда не идёт без доработки.

Частые вопросы

Подходит ли react-admin только для простого CRUD или потянет сложную панель?

Потянет и сложную. Базовый CRUD ты получаешь почти бесплатно по усилиям, а нестандартные экраны - мастера, дашборды, кастомные действия - дописываешь обычными React-компонентами внутри той же панели. Ограничение не в возможностях, а в том, что чем дальше от типовых списков, тем больше кода пишешь руками.

Нужно ли знать React, чтобы работать с react-admin?

Да, базовый React обязателен: компоненты, пропсы, хуки. Визуального конструктора здесь нет, всё описывается кодом. Если React знаком хотя бы на уровне создания компонентов и работы с состоянием, входишь в фреймворк за день-два по официальной документации и туториалу.

Сколько времени занимает запуск базовой панели?

При готовом REST-API рабочий прототип на 3-5 сущностей с фильтрами и авторизацией я поднимаю за один вечер. Основное время потом уходит не на сам react-admin, а на согласование формата данных, кастомные экраны и интеграции с CRM, эквайрингом и доставкой.

Можно ли подключить react-admin к WordPress или WooCommerce?

Можно. У WordPress есть REST API, у WooCommerce - свой REST для заказов и товаров. Пишешь Data Provider, который транслирует вызовы фреймворка в эти эндпоинты и подставляет авторизацию по ключам. Так делают отдельную панель управления магазином, когда штатной админки WooCommerce под конкретный процесс не хватает.