Migrating from v3

Adminator v4 is a ground-up rewrite, not an upgrade. Class names, file paths, and JS APIs all changed. This guide explains what's different, when migration is worth it, and how to stay on v3 if you'd rather not.

Last updated May 21, 2026

Adminator v4 is a rewrite, not an upgrade. If you’re already running v3 in production, treat v4 like a different template that happens to share a name. The class names changed. The file paths changed. The JS module system changed. Bootstrap is gone.

This guide tells you what’s different and helps you decide whether to migrate or stay on v3 (which is still maintained for security updates).

What’s different

Removed

Removed in v4	Replaced by
Bootstrap 5	Custom UI primitives in `_components.scss`, `_ui.scss`, `_forms.scss`
jQuery	Vanilla JS — `querySelectorAll`, `classList`, `addEventListener`
Popper.js	Plain CSS `position: absolute` for dropdowns
Day.js	Native `Intl.DateTimeFormat`
Perfect Scrollbar	Native browser scrollbars styled via CSS
Masonry, Skycons, brand-colors	Unused in v4, removed
AdminatorApp class	`mountShell()` + `initShellBehaviors()` functions in `index.js`
Sidebar / ChartComponent classes	Data-attribute pattern in `init.js`

Added

CSS-variable design system — _tokens.scss defines every color/shadow/radius
Real dark mode — single data-theme attribute on <html>, no class toggling
⌘K command palette — keyboard navigation between pages
Mobile drawer — actual off-canvas sidebar with backdrop and body-scroll lock
Themed library integrations — Chart.js, FullCalendar, jsvectormap all read CSS variables
18 redesigned pages — Dashboard, Email, Calendar, Chat, Compose, Charts, Forms, UI Elements, Buttons, Basic Table, Data Table, Google Maps, Vector Maps, Blank, Sign In, Sign Up, 404, 500

Bundle size

Metric	v3.0.0	v4.0.0	Δ
Production JS (total)	~4.5 MB	~700 KB	−85%
Production CSS	~280 KB	90 KB	−68%
Top-level npm dependencies	16	8	−50%

The ~85% JS reduction comes mostly from removing Bootstrap, jQuery, and Popper, plus tree-shaking the chart/calendar/map libraries to only the parts the template actually uses.

Should you migrate?

Migrate if:

You’re starting a new project (just use v4 directly)
Your customizations are mostly content (page layouts, copy, branding colors)
You want dark mode, the smaller bundle, or the cleaner JS architecture
You’ve been wanting an excuse to drop jQuery and Bootstrap

Stay on v3 if:

Your v3 build is in production and stable
You have substantial custom code wired into v3’s class structure (extending Sidebar, AdminatorApp, custom Chart components)
You depend on Bootstrap utility classes you haven’t replaced
You can’t justify the engineering time to port

v3 will continue to receive security updates for at least 12 months from the v4 release date. See Staying on v3 below.

Migration path

There’s no automated upgrade — class names and APIs are different enough that there’s nothing to script.

The least painful approach: treat v4 as a fresh template.

1. Start fresh from v4

Clone v4 in a new directory. Don’t try to merge into your v3 project.

git clone https://github.com/puikinsh/Adminator-admin-dashboard.git adminator-v4
cd adminator-v4
npm install
npm start

2. Port your content

For each custom page in your v3 project:

Copy the HTML structure from v4’s blank.html
Drop your page’s content into the .content section
Update the data-active and data-crumbs attributes
Replace v3 class names with v4 equivalents (see the mapping below)

3. Port your theme overrides

In v3, brand colors lived in Bootstrap $primary SCSS variables. In v4, they live in --primary CSS variables.

/* v3 — Bootstrap variable override */
$primary: #14B8A6;

/* v4 — CSS variable in _tokens.scss */
:root[data-theme="light"] { --primary: #14B8A6; }
:root[data-theme="dark"]  { --primary: #2DD4BF; }

See Theming for the full list of v4 tokens.

4. Port custom JS

If you wrote custom code that extended v3’s Sidebar, AdminatorApp, or ChartComponent classes, those classes no longer exist. v4 uses a function + data-attribute pattern.

v3: class MySidebar extends Sidebar { ... } → v4: add to NAV in Shell.js, register custom click handlers in init.js
v3: custom chart via ChartComponent → v4: add a seed to SEEDS in charts.js and a <canvas data-chart-key="..."> to your page (see Charts)
v3: custom drawer behavior → v4: see initMobileDrawer() in init.js

5. Update build commands

v3	v4
`npm run dev`	`npm start` (port 4000)
`npm run build:production`	`npm run release:minified`
`npm run lint`	`npm run lint` (same)

6. Class names

There isn’t a clean v3 → v4 class name map — v3 was Bootstrap 4 plus Adminator-specific utility classes, v4 is a custom design system with its own naming. The fastest migration path is not to translate class-by-class, but to:

Open a v4 page that resembles what you’re building (e.g. src/index.html for dashboard-style pages, src/forms.html for forms, src/signin.html for auth)
Copy the markup structure verbatim
Drop your data and copy into the right slots

Trying to translate Bootstrap utility classes (bg-light, text-muted, col-md-6) one-by-one creates a Frankenstein hybrid that doesn’t match either v3 or v4’s visual language. Working from a v4 reference page is faster and gives a coherent result.

A few classes that are easy to misread:

The sidebar is .d-sidebar (not .sidebar or .app-sidebar) — the d- prefix is for the dashboard chrome
The topbar is .d-topbar; the footer is .d-footer
The main content wrapper is .content, inside .main, inside .shell
Cards are .card, buttons are .btn with modifiers like .btn--primary
Color utilities are CSS variables (var(--primary), var(--t-muted)), not Bootstrap-style class utilities

For everything else, the src/*.html files are the source of truth — there’s no class library page to cross-reference.

Staying on v3

The v3 codebase lives on the legacy-v3 branch. It will continue to receive security updates for at least 12 months from the v4 release date (April 2026).

Clone v3 directly

git clone -b legacy-v3 https://github.com/puikinsh/Adminator-admin-dashboard.git adminator-v3
cd adminator-v3
npm install
npm run dev

Pin v3 from npm

npm install adminator-admin-dashboard@^3

This pins your project to the v3 line — security patches in 3.x will install via npm update, but you won’t accidentally upgrade to v4.

What you’ll get on v3

Bug and security fixes
Dependency updates that don’t break the existing API
No new features
No new pages
No design refresh

v3 development is in maintenance mode. New feature work happens on v4.

Why a rewrite instead of an upgrade?

A short note on the decision, for context:

v3 still carried the architecture of the original 2017 template — Bootstrap 4 + jQuery, with v3’s added utility modules layered on top. Cleaning that up incrementally would have meant maintaining two parallel systems (legacy Bootstrap components and new ones) for years, with users perpetually having “half-migrated” projects.

Starting clean with v4 made it possible to:

Drop ~3.8 MB of JS dependencies in one move
Build the design system around CSS variables from day one (instead of retrofitting)
Ship real dark mode (which is hard to add to a Bootstrap-based template after the fact)
Cut the asset surface area to something a small team can actually maintain

The cost is migration friction for v3 users — which is why v3 stays maintained for 12+ months, and why this guide exists.