Getting started

From the zip to a running dashboard in three commands.

Open in demo

Requirements

Requirement	Version
Node.js	^20.19.0 || >=22.12.0. The repository pins 24 in .nvmrc.
npm	The version that ships with your Node. The lockfile is npm's.

Check what you have:

node --version
npm --version

The template ships an .npmrc with legacy-peer-deps=true. Leave it in place: the install resolves against it.

Install and run

Unzip and enter the folder

cd smart-admin

Install the dependencies

npm install

It takes about a minute.

Start the dev server

npm run dev

Vite serves on http://localhost:5173, or the next free port if that one is taken. It prints the address it chose.

Sign in

The form arrives filled with admin@admin.com and 12345678. Press Sign in and you land on /dashboard.

With the demo backend on, any email and any password of six characters or more are accepted: it answers /auth/* in the browser and returns a Demo User who can do everything. Nothing reaches a network.

The demo backend

The zip ships a .env.development that sets two variables:

VITE_USE_MOCK_AUTH=true
VITE_DEMO_MODE=true

VITE_USE_MOCK_AUTH turns on the demo backend: the auth mock and every demo module's data, answered in the browser. VITE_DEMO_MODE only pre-fills the sign-in form. It shows no banner and changes nothing else.

When you connect your real API, delete both lines. Connect your API has the rest. .env.example documents the API, auth, realtime and demo variables, with what each one does.

Vite reads .env.development only for npm run dev. A production build does not see it, so npm run build and npm run preview run without the demo backend and expect a real API.

Build for production

npm run build
npm run preview

build type-checks and bundles in parallel, and writes dist/. Every asset is also written as .gz and .br, so a static host can serve the compressed file directly. preview serves dist/ so you can check the real build before you deploy it.

Set ANALYZE=true before npm run build and the build also writes dist/stats.html, a treemap of every chunk with its gzip and brotli size.

Deploying is its own page: Deployment.

The npm scripts

Script	What it does
dev	Vite dev server on port 5173.
build	Type-check and build in parallel, into dist/.
preview	Serve the built dist/ locally.
build-only	The build without the type-check.
type-check	vue-tsc --build over src/ and the config files.
check:i18n	Fails when the code names a translation key the base locale does not define, when a locale key name contains a dot, or when a message does not compile.
lint	ESLint over the repository, fixing what it can.
smart-admin	The CLI. npm run smart-admin -- --help lists the commands.
generate	Shortcut for smart-admin generate.
analyze	Shortcut for smart-admin analyze.

There is no test script. The zip ships no test runner, so add the one your team uses. Vitest fits the Vite setup: npm install -D vitest jsdom @vue/test-utils, then a test script and a vitest.config.ts.

Where to go next

• Project structure — what lives where.
• Add a module — your first feature, with the CLI.
• Connect your API — swap the mock for a real backend.
• Theming — make it yours in five minutes.