vue-naive-admin: a JavaScript-first Vue 3 admin template with a real NestJS backend

Who vue-naive-admin is built for, and the choice that defines it

The README states the target audience directly: small and medium businesses, students and individual developers who need to get an admin project moving. The stated design principle is that simplicity wins, and the concrete expression of that principle is a decision most Vue admin templates make the other way. The front end is JavaScript, not TypeScript. The README calls the project one of the few Vue 3 admin templates written in JavaScript and treats that as a feature rather than a gap.

That single choice shapes everything else. There is no type layer to keep in sync with the API, no generics to learn before you can add a page, and jsconfig.json sits at the repository root instead of a tsconfig. The trade-off is equally clear: nothing checks your props, your store shapes or your API payloads at build time. If your team already runs TypeScript everywhere, this template will feel like a step backwards, and the README does not pretend otherwise. If your team is small and the priority is shipping screens this week, the missing type layer removes a category of work.

The repository layout supports the claim of low coupling. The top level holds build/, src/, public/, uno.config.js, vite.config.js and eslint.config.js, and the README describes the file structure as having zero coupling between modules, so deleting one business module does not affect the others. That is a claim about the template's own organisation, not a guarantee about whatever you add on top of it.

Flat routing, permission-generated menus and the Redis refresh flow

The routing model is the part worth understanding before you write any code. The README describes a flat route design where every component can be a page, which the project presents as an answer to the KeepAlive problems that appear with deeply nested routes. Routes are then generated dynamically from permissions rather than declared twice. The README makes a specific point about error handling here: 403 and 404 are distinguishable, so an authenticated user without rights does not simply land on a 404 page.

Menus are not a front-end concern. The README says menu resources are controlled by the backend, which means adding or changing a menu is done through the resource management screen after you connect the backend, followed by granting that resource to a role in role management. This is the single most common confusion the README anticipates, and it is a real constraint: without a backend, the menu system has nothing to read from. The escape hatch is /src/settings.js, where basePermissions can hold menu definitions that bypass permission control, as long as they match the resource structure shown in the interface documentation.

Authentication uses JWT through the companion NestJS service, and the README describes a Redis-backed silent refresh so a user's login state stays controllable without forcing a re-login. That is a backend-side feature. The front end alone cannot provide it, and the README does not describe a fallback for deployments without Redis.

Installing vue-naive-admin and running it for the first time

The README offers two ways to start. The first is GitHub's template mechanism, which creates a new repository from the project. The second is degit, which the README recommends when you do not want the project's commit history carried into your own repository. Run it from an empty directory:

npx degit zclzone/vue-naive-admin

After the files land, install dependencies. The repository ships pnpm-lock.yaml and pnpm-workspace.yaml, so pnpm is the package manager the lockfile corresponds to. Note that package.json defines a postinstall script that runs npx simple-git-hooks, so the install step also wires up the pre-commit hook that runs lint-staged.

pnpm install

Then start the development server. The dev script is plain vite, and the repository has separate .env.development and .env.production files at the top level, so environment values come from those files rather than from flags on the command line.

pnpm dev

For a production bundle, the build script is vite build and preview serves the result locally:

pnpm build
pnpm preview

The package also defines a lint:fix script that runs eslint --fix, and an up script that runs taze major -I for interactive major-version dependency bumps. That last one rewrites dependency versions, so run it on a clean working tree.

What you get on first load is the template shell with its layout, theme and example pages. What you do not get is a working menu tree unless you either point the front end at the NestJS backend or populate basePermissions in /src/settings.js. The README points to the project documentation for the backend connection steps and to the interface documentation for the resource JSON shape.

The backend dependency is the template's sharpest edge

Many admin templates ship with mock data and let you defer the backend decision indefinitely. vue-naive-admin 2.0 does not take that route. The README states plainly that 1.0 was front-end only with mocks while 2.0 is a full-stack release with real backend interfaces, and that 2.0 is both less complex and more flexible than 1.0 despite the higher version number. The backend lives in a separate repository, isme-nest-serve, built on NestJS, TypeORM and MySQL, with JWT and RBAC plus the basic endpoints the template needs.

That is a genuine architectural commitment. If you already have an API, you are not adopting a template so much as reverse-engineering a contract: the front end expects particular response shapes for menus, roles and permissions, and the README's answer to menu questions assumes those endpoints exist. The interface documentation is the reference for the resource structure, and it is a separate site from the project documentation.

The project does list three community backends that have already been adapted to 2.0: isme-java-serve on SpringBoot, MybatisPlus and SaToken; naive-admin-go on gin, gorm, mysql, jwt and session; and isme-java on Springboot 3 and JDK21. Their existence is useful evidence that the contract is portable, but the README does not describe a compatibility guarantee, a version pin or a conformance test for any of them. Treat them as starting points to read, not as drop-in services.

Where Naive UI and Unocss carry the weight, and where they do not

The component layer is Naive UI, and the README's claims about it are specific: an extremely concise code style, a clean page design, and theme customisation that is described as easy. The project also wraps Naive UI in two directions. A global message utility is exposed as a method, with support for batched notifications and a cross-page singleton, which addresses the common problem of the same toast appearing from several components at once. On top of that sit business components including a Page component, a CRUD table component and a Modal component, intended to remove repetitive work.

Styling is Unocss with the iconify integration, and the README notes support for custom icons and dynamic rendering. The build dependencies include @unocss/preset-rem-to-px, so the atomic classes are converted from rem to px at build time, which changes how you reason about responsive sizing compared with a default Unocss setup. State is Pinia with pinia-plugin-persistedstate, so store persistence is available without writing the storage glue yourself.

The honest limitation is that none of this is verified by the README beyond the feature list. The performance section consists of two screenshots hosted on the documentation site, with no methodology, no hardware description and no reproduction steps. If performance is the reason you are considering this template, the screenshots are not evidence you can act on. The dependency versions in package.json are the more useful signal, and several of them are recent majors: vue-router 5.x, vite 8.x, eslint 10.x and @antfu/eslint-config 9.x. A template tracking that aggressively will accumulate breaking dependency changes faster than a conservative one.

How vue-naive-admin differs from Vue3-element-admin and other Vue admin templates

The most direct comparison is with Vue3-element-admin, which appears in the related searches for this project. The difference is not cosmetic. Vue3-element-admin is built on Element Plus; vue-naive-admin is built on Naive UI, which is a Vue 3 native component library with a different theming model and a different set of component APIs. Choosing between them is largely choosing which component library your team already knows, because the surrounding stack (Vite, Pinia, Vue Router) is common ground.

The second difference is the TypeScript decision. Vue3-element-admin is a TypeScript project. vue-naive-admin is not, and the README presents that as its distinguishing position in the market. If you compare the two on tooling alone, the TypeScript project wins on static checking. If you compare them on the amount of type plumbing between you and a finished screen, this template asks for less.

The third difference is the backend. This project ships a companion NestJS implementation and documents three community ports in Java and Go. A template that only provides mocks leaves the API contract entirely to you. Neither approach is strictly better: a defined contract saves design time and constrains you, while no contract is flexible and slower to start. The README's own framing is that 2.0 being a full-stack release is an improvement over 1.0's mocks, which tells you where the author thinks the value sits.

Licence, maintenance and what an upgrade actually costs

The project is MIT licensed. The README spells out the practical effect: anyone may use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software, and pass the same rights on, provided the original copyright and licence information is retained, including in file headers. The README summarises the author's intent as keeping the copyright and adding no other restriction. For a template you fork into a private product, that means keeping the LICENSE file and the copyright notices in place. This is a description of the licence text, not legal advice for your situation.

Maintenance is the part to check yourself. The most recent release listed is v2.0.0 from 2023-12-20, and the last push to the repository was on 2026-08-29. Those two facts point in different directions: the tagged release line has been quiet for a long time, while the default 2.x branch has seen recent commits. The README does not document a migration path from 1.0 to 2.0 beyond the note that 2.0 was redesigned from scratch, which means an upgrade between those versions is closer to a rewrite than to a dependency bump. Nothing in the README describes a migration guide for future major versions either.

The dependencies are the real upgrade cost. With vite, eslint, vue-router and the Antfu config all on major versions that move quickly, and with an up script that runs taze major -I to bump majors interactively, the maintenance work is keeping a large dependency graph coherent. Budget for that, and run the bump on a branch rather than on your main line.

Editorial conclusion

Adopt vue-naive-admin if you want a Vue 3 admin shell that stays in JavaScript and you are willing to run the NestJS backend or map the permission model onto your own API. Do not adopt it if you need a TypeScript front end, a documented upgrade path between major versions, or a menu system that works without a backend. Before committing, check that /src/settings.js basePermissions matches the resource JSON shape in the interface documentation, confirm the last push date on the 2.x branch, and read the MIT licence text for the attribution clause.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zclzone/vue-naive-admin on GitHub