Open-source project
soybeanjs/soybean-admin avatar
soybeanjs/soybean-admin

SoybeanAdmin Vue3 tutorial: file routing, pnpm workspaces and the end of the 2.x line

A clean, elegant and powerful admin template based on Vue3, Vite, TypeScript, Pinia, NaiveUI and UnoCSS.

15,340 stars2,548 forksTypeScriptMIT

At a glance

What is it?
SoybeanAdmin is a Vue 3 admin template you clone and edit, built on Vite8, NaiveUI, Pinia and UnoCSS. Its generated routes and workspace packages are solid groundwork, but 2.3 is the final feature release before a 3.0 rebuild on a different foundation.
Who is it for?
Pick SoybeanAdmin 2.3 if you need a Vue 3 back office now, are comfortable with pnpm, and can live on a line that gets maintenance fixes but no new features. Skip it if your team is locked to npm or yarn, or if you want a template you can upgrade by bumping a version, since every upstream change arrives as a merge into your fork.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 25 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • soybeanjs/soybean-admin15,340 ★ · +315
Star history
Repository2026-09-212026-11-15
soybeanjs/soybean-admin15k15.3k

315 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A Vue 3 admin template split into @sa workspace packages

SoybeanAdmin is a codebase you fork, not a library you install. You clone the repository, delete the pages you do not need and build your back office inside it, so every later upgrade is a merge rather than a version bump. Version 2.3.0 is built on Vue3, Vite8, TypeScript, Pinia, NaiveUI and UnoCSS, and package.json pins its third-party dependencies to exact versions: naive-ui 2.45.3, echarts 6.1.0, @vueuse/core 15.0.0, dayjs 1.11.23.

Shared code sits outside src/ in workspace packages that the app imports by name. @sa/axios, @sa/color, @sa/hooks, @sa/materials and @sa/utils are all declared as workspace:* dependencies and resolved from the packages/ directory through pnpm-workspace.yaml. That layout gives the HTTP wrapper, the color helpers and the layout materials their own folders and boundaries, which keeps application pages separate from plumbing. Out of the box you get 403, 404 and 500 pages, layout and tab components, a theme configuration panel tied into UnoCSS, built-in i18n and an adaptive layout for mobile screens. The target reader is a Vue developer who wants those pieces on day one and would rather edit working code than assemble it from scratch.

Elegant Router generates the route table and its types

Routes in SoybeanAdmin are generated from the views you create. The template uses Elegant Router, a separate soybeanjs project, to write route imports, route declarations and the matching TypeScript types. In package.json this surfaces as `pnpm gen-route`, which forwards to `pnpm sa gen-route`.

That `sa` command is the template's own CLI, and it carries more than routing. `pnpm commit` runs `sa git-commit`, `pnpm commit:zh` passes `-l=zh-cn` for Chinese commit prompts, `pnpm cleanup` and `pnpm upkg` handle housekeeping and dependency updates, and `pnpm release` drives releases. Type checking is a separate script, `vue-tsc --noEmit --skipLibCheck`, behind `pnpm typecheck`. Linting chains `vp lint --fix` with `eslint --fix .`, and the README names eslint, oxlint, oxfmt and vp hooks as the enforced code standard, with a .vite-hooks/ directory at the root.

Generated route types let the compiler catch a reference to a page name that no longer exists. The price is a convention you have to learn before you add your first page. Hand edits to generated files fight the generator, and the README sends readers to the Elegant Router repository for the naming rules instead of spelling them out on the main page.

Static routes, backend routes and the test mode that dev runs by default

Permission routing has two modes. The README states that SoybeanAdmin supports front-end static routes and back-end dynamic routes, so a project can ship its menu in the bundle or let a server decide what each user sees. Teams with an existing permission service should look at the second mode first, since the server then has to return route data in the shape the template consumes, and that contract lives on the documentation site at docs.soybeanjs.cn rather than in the README.

Environment settings are split across .env, .env.test and .env.prod at the repository root, and the npm scripts pick a Vite mode explicitly. `pnpm dev` runs `vp dev --mode test`. `pnpm dev:prod` runs `vp dev --mode prod`. `pnpm build` produces a prod bundle with `vp build --mode prod`, and `pnpm build:test` builds against test settings. The everyday dev server therefore reads the test environment, not production, so check .env.test before pointing a local session at a real API. Note also that these scripts call a `vp` binary rather than `vite` directly, and `pnpm install` triggers `vp config --no-agent` through the prepare hook.

Mock data is handled online through ApiFox, according to the README's introduction, rather than by a mock server inside the repository.

Cloning soybean admin from GitHub, Gitee or GitCode and starting the dev server

Three tools are required: git, Node.js 20.19.0 or newer, and pnpm 10.5.0 or newer. The project is mirrored on three hosts, and the README gives a clone command for each. Pick the one closest to your network.

bash
# github
git clone https://github.com/soybeanjs/soybean-admin.git
# gitee
git clone https://gitee.com/honghuangdc/soybean-admin.git
# gitcode
git clone https://gitcode.com/soybeanjs/soybean-admin.git

Inside the cloned folder, install dependencies with pnpm. This also links the @sa workspace packages into the app.

bash
pnpm i

Then start the development server, which runs in test mode as described above.

bash
pnpm dev

When the pages render the way you expect, produce a production bundle:

bash
pnpm build

If you want to see the result before cloning anything, the NaiveUI demo is hosted at naive.soybeanjs.cn. For a guided walkthrough, the maintainers publish a quick-start video series on Bilibili, and the docs site carries a code sync guide at docs.soybeanjs.cn/zh/guide/sync for pulling upstream changes into a fork. That guide matters more than it sounds: once you have edited the template, upstream fixes reach you only through that sync process.

2.3 is the last 2.x feature release, and 3.0 rebuilds on ubean and VeanUI

The biggest constraint on adopting SoybeanAdmin today is its own roadmap. A warning at the top of the README says 2.3 will be the last maintained major version of the 2.x series. From here, 2.x receives maintenance updates on that version only, and new features go into 3.0, which is being rebuilt as a whole on the ubean full-stack framework and the VeanUI component library. The README advises new projects to follow the 3.0 progress, tracked in Roadmap Issue #941.

The repository is not idle. v2.3.0 shipped on 2026-10-09, v2.2.0 and v2.1.1 both landed on 2026-05-13, and the last push was on 2026-10-21. The issue is direction, not activity.

For a reader, the consequence is concrete. A back office started on 2.3 is built against NaiveUI pages and the current @sa packages, and the next major version swaps the foundation underneath them. Moving from 2.x to 3.0 will not be a dependency bump. Before committing a long-lived internal tool to 2.3, open Issue #941 and check whether the maintainers describe a migration path, and budget for staying on 2.3 if they do not.

pnpm is mandatory and the backend is a community project

SoybeanAdmin will not install cleanly with npm or yarn. The README says so directly: because the project uses a pnpm monorepo, do not use npm or yarn to install dependencies. Teams whose CI images or lockfile policies assume npm have to add pnpm 10.5.0 or newer before the template builds at all.

The second gap is the server. The repository layout (src/, packages/, build/, public/, vite.config.ts, uno.config.ts) is front-end only, and the README's ecosystem list is where backends come from. For soybean admin Java users there is pea, built on SpringBoot 3.2 with JDK 21, MyBatis-Plus and Spring Security, and PanisAdmin on SpringBoot3, SaToken and MySQL with menu and button level permissions. Go users get soybean-admin-go, which uses gin and gorm and targets the template's example branch, or ba on GoFrame. FastSoyAdmin pairs the front end with FastAPI.

None of these are maintained by the SoybeanAdmin team. The dynamic routing contract has to match on both sides, so a third-party backend written against an older template branch can fall out of step with 2.3.0. Check which branch or version each backend was built for before you wire it to a fresh clone.

Element Plus, Ant Design Vue and React versions of the same layout

The NaiveUI repository is one of several siblings. soybean-admin-antd carries the same template on Ant Design Vue, with a demo at antd.soybeanjs.cn, and soybean-admin-element-plus does the same for Element Plus, with a demo at elp.soybeanjs.cn. A legacy branch of the main repository keeps the older design alive at legacy.soybeanjs.cn, documented separately at legacy-docs.soybeanjs.cn. The real difference between them is the component library your pages are written against. If your team already has Element Plus forms and tables, the Element Plus sibling saves rewriting them in NaiveUI.

These are separate repositories, each mirrored to GitHub, Gitee and GitCode, so fixes do not automatically appear in all of them. The 2.3 and 3.0 notices quoted above sit in the NaiveUI repository's README, so read each sibling's own README for its status.

Outside Vue, skyroc-admin is a community React implementation of SoybeanAdmin. It shares the visual design, not the code, so nothing in the Vue tooling (Elegant Router, the `sa` CLI, the @sa packages) carries over.

The template is MIT licensed, which allows forking it into a closed internal product as long as the license notice is kept. The maintainers also sell custom development and outsourcing built on SoybeanAdmin, reachable at [email protected].

Editorial conclusion

Pick SoybeanAdmin 2.3 if you need a Vue 3 back office now, are comfortable with pnpm, and can live on a line that gets maintenance fixes but no new features. Skip it if your team is locked to npm or yarn, or if you want a template you can upgrade by bumping a version, since every upstream change arrives as a merge into your fork. Before starting, read Roadmap Issue #941 to see how far the ubean and VeanUI rebuild has progressed, because the README itself tells new projects to watch 3.0.

Frequently asked questions

Which Node.js and pnpm versions does SoybeanAdmin require?

The README asks for Node.js 20.19.0 or newer and pnpm 10.5.0 or newer, plus git to clone the repository. npm and yarn are not supported because the project is a pnpm monorepo.

Is there a SoybeanAdmin version for Element Plus, Ant Design Vue or React?

Element Plus and Ant Design Vue versions live in the soybean-admin-element-plus and soybean-admin-antd repositories, each with its own demo. skyroc-admin is a community React implementation listed in the README's ecosystem section.

Should a new project start on SoybeanAdmin 2.3 or wait for 3.0?

The README says 2.3 is the last maintained major version of 2.x and will only receive maintenance updates, while new features go into 3.0, a rebuild on ubean and VeanUI. It recommends that new projects follow 3.0 progress in Roadmap Issue #941.

Does SoybeanAdmin come with a Java or Go backend?

The repository is a front-end template. The README lists community backends such as pea (SpringBoot 3.2 and JDK 21), soybean-admin-go (gin and gorm) and FastSoyAdmin (FastAPI).

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. soybeanjs/soybean-admin on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/soybeanjs-soybean-admin.svg)](https://hysenlabs.com/projects/soybeanjs-soybean-admin)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/soybeanjs-soybean-admin.svg)](https://hysenlabs.com/projects/soybeanjs-soybean-admin)

Was this useful?