Відзначимо: коли стандартна адмін-панель занадто жорстка, а кастомна розробка — занадто дорога, AdminJS (див. GitHub-репозиторій) пропонує золоту середину. Але в коробці він часто не покриває складні бізнес-правила: кастомні екшени, завантаження файлів, рольовий доступ. Ми розробили адмін-панелі на AdminJS для e-commerce, логістики та SaaS з 20+ проєктами. Одного разу для мережі магазинів ми впровадили кастомний екшен масової зміни цін — обробка 5000 товарів за 30 секунд. У цій статті розповімо, як кастомізувати AdminJS, які інструменти використовуємо і де проходять межі можливостей.
Які проблеми вирішує AdminJS?
AdminJS генерує CRUD-інтерфейс на основі моделей даних. Він підходить для швидкого запуску адмінки, але потребує доопрацювання під нестандартні сценарії. Ось основні складнощі, які ми вирішуємо:
- Кастомні дії — масова розсилка, генерація звітів, інтеграція із зовнішніми API. Наприклад, для логістичного стартапу ми додали екшен автоматичного створення накладних, що обробляє 10 000 записів за хвилину.
- Завантаження файлів — через
@adminjs/uploadз S3 або локальним сховищем. Підтримуємо автогенерацію прев'ю та мініатюр для зображень товарів. - Права доступу — розмежування за ролями та діями (перегляд, редагування, видалення). Налаштовуємо рольову модель на основі
currentAdmin.roleз каскадними дозволами. - Кастомні компоненти — заміна стандартних полів на React-віджети: datepicker, autocomplete, wysiwyg-редактори. Для одного клієнта ми розробили компонент вибору складу з геолокацією.
- Продуктивність — оптимізація запитів для таблиць з 100k+ записів: додаємо індекси, використовуємо серверну фільтрацію, підключаємо Elasticsearch для повнотекстового пошуку.
Як кастомізувати AdminJS під бізнес-вимоги?
Стек: Node.js, TypeScript, React 18, AdminJS 7.x, TypeORM / Prisma. Деплой — Docker, Nginx, Vercel.
Розглянемо приклад: інтернет-магазин з товарами, замовленнями та клієнтами. Базова налаштування AdminJS з автентифікацією та кастомними правами:
Приклад коду налаштування AdminJS
import AdminJS from 'adminjs'; import AdminJSExpress from '@adminjs/express'; import { Database, Resource, getModelByName } from '@adminjs/typeorm'; AdminJS.registerAdapter({ Database, Resource }); const adminJs = new AdminJS({ resources: [ { resource: getModelByName('User'), options: { properties: { password: { isVisible: { list: false, edit: false, filter: false, show: false } }, createdAt: { isVisible: { edit: false } } }, actions: { delete: { isAccessible: ({ currentAdmin }) => currentAdmin?.role === 'superadmin' } } } }, { resource: getModelByName('Order'), options: { listProperties: ['id', 'customer', 'status', 'total', 'createdAt'], filterProperties: ['status', 'createdAt'], sort: { sortBy: 'createdAt', direction: 'desc' } } } ], dashboard: { component: AdminJS.bundle('./components/Dashboard') }, branding: { companyName: 'Мій Магазин', logo: '/admin-logo.svg' } }); const router = AdminJSExpress.buildAuthenticatedRouter(adminJs, { authenticate: async (email, password) => { const admin = await Admin.findOne({ email }); if (admin && await bcrypt.compare(password, admin.passwordHash)) { return admin; } return null; }, cookiePassword: process.env.COOKIE_SECRET }); Кастомний компонент для відображення статусу замовлення кольором:
import { BasePropertyProps } from 'adminjs'; const OrderStatusCell: React.FC<BasePropertyProps> = ({ record }) => { const status = record.params.status; const colors = { pending: 'orange', completed: 'green', cancelled: 'red' }; return <span style={{ color: colors[status] }}>{status}</span>; }; export default OrderStatusCell; Завантаження зображень товарів у S3 через @adminjs/upload:
import uploadFeature from '@adminjs/upload'; import { s3Client } from './s3-client'; { resource: getModelByName('Product'), features: [ uploadFeature({ provider: { aws: { bucket: 'my-bucket', s3Client } }, properties: { file: 'imageFile', filePath: 'imageUrl', filename: 'imageName', mimeType: 'imageMimeType' }, uploadPath: (record, filename) => `products/${record.id()}/${filename}` }) ] } Чому AdminJS економить до 60% часу та бюджету?
Написання адмін-панелі з нуля на React і Express займає близько 3–4 тижнів для типового CRUD. AdminJS скорочує цей термін до 1–2 тижнів, що в 2-3 рази швидше. Для проєктів з 10+ сутностями економія часу сягає 60%, а отже і бюджету. При додаванні кастомних компонентів економія зберігається на рівні 30–40%.
Згідно з офіційною документацією AdminJS, фреймворк підтримує всі популярні ORM і прискорює розробку за рахунок генерації інтерфейсу з моделей. Але важливо розуміти: коробкова версія дає базовий функціонал, а реальна економія отримується при правильному налаштуванні та кастомізації.
| ORM | Швидкість розробки | Складність кастомізації |
|---|---|---|
| TypeORM | Висока | Низька |
| Prisma | Середня | Середня |
| Mongoose | Висока | Низька |
| Sequelize | Середня | Середня |
Що робити, якщо продуктивність AdminJS не влаштовує?
Для таблиць з 100k+ записів стандартні механізми можуть гальмувати. Ми застосовуємо кілька підходів. Перший — серверна фільтрація: всі фільтри виконуються на стороні БД, а не у фронтенді. Другий — індексація часто запитаних полів. Третій — відмова від find із завантаженням усіх пов'язаних сутностей; використовуємо QueryBuilder з select only. У крайньому випадку підключаємо Elasticsearch для повнотекстового пошуку.
Приклад оптимізації: в одному проєкті таблиця замовлень (200k записів) відкривалася 5 секунд. Після додавання композитного індексу по (status, createdAt) і фільтрації за статусом час завантаження впав до 200 мс.
Як ми розробляємо адмін-панель?
| Етап | Час (дні) |
|---|---|
| Аналітика | 1 |
| Проектування | 1-2 |
| Реалізація | 5-10 |
| Тестування | 2-3 |
| Деплой | 1 |
- Аналітика — вивчаємо структуру даних, бізнес-процеси, права доступу. Оцінюємо обсяг за 1 день.
- Проектування — визначаємо ресурси, екшени, компоненти, схему прав.
- Реалізація — налаштування AdminJS, написання кастомних компонентів і екшенів, інтеграція із зовнішніми сервісами.
- Тестування — перевірка сценаріїв, навантажувальне тестування (до 10 000 запитів).
- Деплой і документація — розгортання на вашому сервері, опис інструкцій для адміністраторів.
Що входить в результат роботи
- Повністю готова адмін-панель на AdminJS з автентифікацією.
- Кастомні компоненти та екшени за вашим ТЗ.
- Інтеграція із завантаженням файлів (S3, MinIO).
- Розмежування прав доступу (ролі, дії).
- Вихідний код, документація, інструкція з розгортання.
- Гарантія 6 місяців на виявлені помилки.
Для простих проєктів AdminJS скорочує час розробки адмінки на 60% порівняно з написанням з нуля. Зв'яжіться з нами, щоб обговорити ваш проєкт — отримайте консультацію та попередню оцінку за 1 день. Замовте розробку адмін-панелі на AdminJS.