Skip to content

README.md

Latest commit

 

History

History
180 lines (127 loc) · 9.03 KB

README.md

File metadata and controls

180 lines (127 loc) · 9.03 KB

@guanzhu.me/arco-cli

Scaffold a modern Arco Design admin app — Vite 7 + React 18 + strict TypeScript — in under a minute. A maintained fork of the unmaintained arco-cli, with a bundled modern starter that fixes the years-stale stack of the official arco-design-pro.

npm license node CI Demo

English · 中文 · Live demo ↗ · Deploy guide

Arco Pro demo — login, theme cycle, search-table mock data

Note

This is a community-maintained fork — not endorsed by the Arco Design team. The legacy official templates (arco-design-pro, @arco-materials/*) remain wired up; the bundled "Arco Pro (Unofficial)" template is the differentiator.

Why this exists

The official arco-design-pro is excellent but its last release shipped in 2024-04 and the stack is showing its age. Meanwhile the upstream arco-cli was abandoned and stopped working on modern Node.

This fork keeps the CLI working and ships a bundled template that's a modern rebuild of Arco Pro:

Official arco-design-pro Bundled pro-recommend
Build Webpack 4 / Vite (mixed) Vite 7
React 16 18.3 (React 19 ready when Arco fixes cloneElement(child.ref))
TypeScript loose strict + noImplicitOverride
Server state hand-rolled axios TanStack Query v5
Client state redux-thunk Zustand v5 (persisted)
Forms Arco Form only react-hook-form + zod via a tiny <Field> bridge
Mock layer mockjs (deprecated) MSW v2 + @faker-js/faker
i18n Arco's locale only i18next + react-i18next
Lint ESLint legacy ESLint 9 flat config + tsc --noEmit gating builds
Tests none vitest + Playwright smoke E2E
Bundle analysis none npm run analyze (rollup-plugin-visualizer)
Dependency rot dead react-color, mockjs, query-string, … cleaned up

Plus: charts moved to VChart, route-level + chunked code splitting, lazy-imported MSW (prod entry is ~289 KB vs ~1.15 MB without the split), per-route document titles via react-helmet-async, react-error-boundary at the page boundary, prefers-color-scheme-aware theme cycle.

Quick start

npx @guanzhu.me/arco-cli init my-app
cd my-app
npm install   # if you used --skip-install
npm run dev

Or install globally:

npm i -g @guanzhu.me/arco-cli
arco init my-app

The interactive prompt lets you pick the template; pass --template to skip it:

arco init my-app --template pro-recommend          # bundled Unofficial, full preset
arco init my-app --template pro-recommend:simple   # bundled Unofficial, dashboard-only preset
arco init my-app --template arco-design-pro        # official (legacy, 2024-04)

What's in the bundled template

src/
├── api/             # axios client + TanStack Query hooks per resource
├── auth/            # useAuth() + <ProtectedRoute> + <Access>/useAccess (RBAC + fine-grained — see docs/auth-backend.md)
├── components/      # NavBar, Chart wrappers, Settings drawer, Form/Field bridge
├── i18n/            # i18next bootstrap (en + zh-CN)
├── layout/          # PageLayout, breadcrumb + route flatten
├── mock/            # MSW worker + central handler registry
├── pages/           # dashboard / list / form / user / visualization / exception / welcome
├── store/           # Zustand store (settings)
└── style/           # global.less + Arco theme tokens
e2e/                 # Playwright smoke (login, mock data, theme cycle, 404)

Built-in scripts:

Script What it does
npm run dev Vite dev server with HMR
npm run build tsc --noEmit then vite build
npm run typecheck strict TS check
npm run lint ESLint 9
npm test vitest unit run
npm run test:coverage v8 coverage report
npm run analyze bundle visualiser (sunburst stats.html)
npm run e2e Playwright smoke (auto-boots dev server)
npm run e2e:install one-time Chromium download

Other CLI commands

Add a new page to an existing arco-design-pro-shaped project:

arco add page user-list --type table
arco add page settings  --type blank

Scaffolds src/pages/<name>/{index.tsx,style/index.module.less,locale/index.ts} and, when src/routes.ts + src/locale/index.ts follow the official shape, interactively places the new route + edits both files. Otherwise it prints the snippets to paste.

--type is blank (Card + title) or table (Card with header, primary action, Arco Table).

Generate a typed API hook + zod schema + MSW mock for /api/<name> in one shot:

arco add api user-list                   # → useUserListQuery (GET, list shape)
arco add api user-create --method post   # → useUserCreateMutation
arco add api user --method delete --skip-mock

Writes src/api/<name>.ts (zod schema, query keys, TanStack Query hook), src/mock/<name>.ts (MSW handler with faker data), and edits src/mock/handlers.ts to register the new handler. When handlers.ts doesn't match the upstream shape the CLI prints the two-line snippet to paste manually.

Scaffold a complete CRUD module — page + 4 API hooks + working MSW handlers — in one command:

arco add table user

Creates src/pages/user/{index.tsx,columns.tsx,form.tsx,locale/}, src/api/user.ts with list/create/update/delete hooks, and src/mock/user.ts with handlers that actually mutate an in-memory list (POSTed rows persist for the dev session). Auto-edits src/routes.ts to add a top-level menu entry, src/locale/{en-US,zh-CN}.ts for the menu label, and src/mock/handlers.ts to register the new handlers. Visit /user after running and you have a working table with search, pagination, create/edit drawer, and delete — all driven by zod-validated types.

Other helpers:

arco dev                            # forwards to the project's `npm run dev`
arco upgrade --version latest       # bumps Arco deps in package.json
arco init my-app --template file:../my-template   # local template directory

Custom templates

A template is just an npm package (or local dir) containing either:

  • a template/ directory whose contents are copied verbatim, or
  • a .arco-cli/init.js script exporting an async function for custom logic.

Optional hook/after-init.js or .arco-cli/after-init.js runs after npm install.

Requirements

  • Node.js ≥ 22 (LTS lines 22 + 24)
  • Tested on Windows + Linux (macOS works but isn't in CI)

Deploying the bundled template

Live demo → arco-pro-demo.vercel.app (admin / admin, or anything — the mock layer doesn't validate)

Want to publish your own demo? See docs/deploy.md — covers Vercel (point-and-click, what powers the live demo), Cloudflare Pages dashboard, and notes on GitHub Pages. MSW intercepts every /api/* in the browser, so the demo runs with zero backend.

Wiring a real backend

The bundled template ships with <Access> / useAccess() for permission gating, with mock-driven roles[] + permissions{} for the demo. To plug in a real backend, see docs/auth-backend.md — covers the UserInfo contract, three permission models (pure RBAC / pure ACL / hybrid), SQL schemas, middleware in Node / Spring / FastAPI / Go, session vs JWT, data-level filtering, and a migration checklist from existing auth.

Notes

A small child_process compatibility shim ships with the CLI so legacy templates (e.g. arco-design-pro) that call spawnSync('npm.cmd', …) directly still work on Node versions that enforce the BatBadBut (CVE-2024-27980) fix.

Status & roadmap

This is a personal-but-public project — releases ship via tag-driven npm publish (Trusted Publishing, no secrets). Recent focus has been on hardening the bundled template (strict TS, modern testing, dead-code cleanup, mock layer fixes). Possible next steps, in no particular order:

  • Storybook integration for the bundled components/
  • Permission DSL (route + element-level gates wired through useAuth)
  • React 19 upgrade when Arco fixes cloneElement(child.ref)

Issues and PRs welcome — see CONTRIBUTING.md and docs/ for setup notes and architecture.

License

MIT — see LICENSE.