gentelella: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository. Cross-tool counterparts: AGENTS.md, .cursor/rules/project.mdc, .github/copilot-instructions.md. Each tool reads only its own file; content overlaps intentionally.

What this is

Gentelella v4 (4.2.0) — free admin dashboard template by Colorlib. 58 production HTML pages under production/, built with Vite 8 (Rolldown). Vanilla ES2022, no Bootstrap, no jQuery, no SPA framework. SCSS-only styling. ECharts 6, DataTables.net 3, and Leaflet 1.9 are the only heavyweight runtime deps — all lazy-imported per page.

Live preview: https://preview.colorlib.com/theme/gentelella/.

Commands

npm run dev                # Vite dev server on :9173, opens /production/index.html
npm run build              # Production build → dist/
npm run preview            # Serve built dist/ on :9174

npm run lint               # ESLint over src/
npm run lint:fix           # Auto-fix
npm run format             # Prettier write
npm run format:check       # Prettier check

npm run new -- <slug>      # Scaffold a new page under production/
npm run screenshots        # Playwright captures 22 pages × light+dark → docs/screenshots/
npm run smoke              # Boot dev server, hit every page, assert 200
npm run analyze            # Build + open dist/stats.html
npm run deploy:preview     # Build + sync to R2 with per-file cache headers

Override the dev port via PORT=…; build under a subpath via BASE_PATH=/foo/ npm run build.

Architecture

Entry point: src/main-v4.js — single bundle for every page. Imports scss/v4/main.scss, mounts the shell, registers ECharts/DataTables/Leaflet placeholders, then lazy-imports page-specific modules guarded by DOM presence:

if (document.getElementById('inbox-root')) {
  import('./v4/inbox.js').then((m) => m.initInbox());
}

Shell injection (vite.config.js shellInjectionPlugin): pages opt in by setting <body data-shell="admin" data-page="key" data-breadcrumb="A > B">. At build/dev time the Vite plugin inlines sidebar/topbar/footer HTML directly into the document so the shell paints on the first frame — no FOUC. Runtime src/v4/shell.js mountShell() is the fallback for raw-file viewing and always wires up event handlers (mobile drawer, theme toggle, sidebar accordion).