Відзначимо: коли стандартна адмін-панель занадто жорстка, а кастомна розробка — занадто дорога, 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.