Skip to content
Get packs

Guide · Open source

How to use soybean-admin: clone, run and build a Vue 3 admin

Updated · written with AI from the project's own documentation and checked against our catalogue data

SoybeanAdmin is an open-source admin template for building back-office web apps such as user management, data and settings pages. It is built on Vue 3, Vite, TypeScript, Pinia, Naive UI and UnoCSS. This guide shows you how to get the project running locally, build it, and understand the parts you will work with first.

SoybeanAdminsoybeanjs/soybean-admin · ★ 15.2k · MIT

Quick start

  1. 1Check prerequisites. Confirm git, Node.js and pnpm are installed and meet the minimum versions in the README.
  2. 2Clone the repository. Run git clone with the GitHub URL, or use a mirror listed in the README.
  3. 3Install dependencies. Change into the project folder and run pnpm i. Do not use npm or yarn.
  4. 4Start the dev server. Run pnpm dev to launch the admin locally and open it in your browser.
  5. 5Build for production. Run pnpm build when you are ready to produce a production build.
  6. 6Customize your app. Edit pages and routes, then use the sample pages and layouts as a starting point for your own admin.

What soybean-admin is and who it is for

SoybeanAdmin is a starter template, not a finished tool. You clone it, install its dependencies, and build your own admin app on top of it. It already includes layouts, themes, internationalization, automatic file-based routing and sample pages such as 403, 404 and 500.

It suits developers starting a new internal admin or back-office app with Vue 3, and anyone who wants to learn a modern Vue stack from a working example. It is not a good fit if you need a ready-to-use product without coding, or if your team uses Vue 2 or React (the README notes a separate React version exists).

Check the prerequisites before you install

The README lists three requirements: git, Node.js at or above the minimum version it states, and pnpm at or above its stated minimum. Check your installed versions against the README before continuing.

The project uses a pnpm monorepo, so do not install dependencies with npm or yarn.

  • git, to clone and manage the project
  • Node.js, at or above the minimum in the README
  • pnpm, at or above the minimum in the README
node -v pnpm -v

Clone the repository and install dependencies

Clone the project from GitHub. The README also lists Gitee and GitCode mirrors if GitHub is slow for you. Then move into the folder and install dependencies with pnpm.

  • Mirrors are listed in the README under the clone section
git clone https://github.com/soybeanjs/soybean-admin.git pnpm i

Start the dev server and build for production

Run the development server to see the admin running locally. When you are ready to ship, run the build command, which the README lists as a separate step.

The README links to the official docs at docs.soybeanjs.cn for further guidance, including a code sync guide.

pnpm dev pnpm build

Learn the features you will use most

SoybeanAdmin includes automatic file-based routing, which generates route imports, declarations and types. It supports both static frontend routes and backend-driven dynamic routes for permissions, so you can choose how access control fits your project.

The project also includes TypeScript with strict type checking, linting tools, a built-in command-line tool for git commits and releases, and mobile-responsive layouts.

  • Automatic file-based routing via Elegant Router
  • Static and backend-driven permission routing
  • Internationalization, themes and layout components
  • Strict TypeScript checking and linting setup

Know the version status before you start

The README says the current 2.x line is in maintenance, with the last planned major 2.x release receiving only maintenance updates. New features are being built for the next major version, which is in development and based on a different full-stack framework and component library.

If you are starting a long-lived project, read the roadmap issue linked in the README before you commit to this line.

What people use it for

  • An internal back-office panel for managing users and settings
  • A starting point for a data dashboard with Vue 3 and TypeScript
  • A learning project for a modern Vue stack with a working example
  • A base for a custom admin system that needs static or backend-driven permission routing

Frequently asked questions

Is soybean-admin free to use?

SoybeanAdmin is released under the MIT license, as stated in the README. You can use it in your own projects under that license; check the LICENSE file in the repository for the full terms.

What do I need installed to run soybean-admin?

You need git, Node.js and pnpm, each at or above the minimum versions listed in the README. The project is set up as a pnpm monorepo, so install dependencies with pnpm rather than npm or yarn.

Why does soybean-admin say not to use npm or yarn?

The README says the project uses a pnpm monorepo structure. Installing with npm or yarn is not supported by the project setup.

Can I use soybean-admin with React or Vue 2?

No. SoybeanAdmin is a Vue 3 project. The README points to a separate React version, skyroc-admin, which is a community project.

What are the alternatives to soybean-admin?

Projects often compared with it include vue-vben-admin, Element Plus admin templates, Naive UI Admin and Vue Admin Better. Pick based on your component library, backend approach and how much structure you want pre-configured.

Is soybean-admin still maintained?

The README says the 2.x line is in maintenance, with 2.3 as the last maintained major version. New features are being developed for the next major version, so check the roadmap before starting a long project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose soybean-admin if you are a developer starting a Vue 3 admin or back-office app and want TypeScript, linting, routing and layouts already set up. Pick something else if you need a finished tool with no coding, or if you want long-term new features on the 2.x line, since the README says new work is going into the next major version.

Install options & downloads