Browse Source
Trim from 161 lines / 9.6KB to 44 lines / 2.6KB (~73% reduction). Keep critical rules and non-obvious architecture essentials; remove content discoverable by reading the codebase directly. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>pull/11775/head
afc163
4 months ago
1 changed files with 24 additions and 140 deletions
@ -1,161 +1,45 @@ |
|||
# CLAUDE.md |
|||
|
|||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
|||
## Project |
|||
|
|||
## Project Overview |
|||
|
|||
Ant Design Pro — an enterprise-class React UI solution built on Umi Max (v4), antd v6, and ProComponents v3. It serves as both a production boilerplate and a live demo of Ant Design's capabilities. |
|||
Ant Design Pro — React enterprise boilerplate on Umi Max v4, antd v6, ProComponents v3. |
|||
|
|||
## Commands |
|||
|
|||
```bash |
|||
# Development |
|||
npm start # Dev server with mock (UMI_ENV=dev) |
|||
npm run dev # Dev server without mock |
|||
npm run start:no-mock # Start with MOCK=none, proxy to real backend |
|||
npm run start:pre # Pre-production environment |
|||
npm run start:test # Test environment |
|||
|
|||
# Build & Preview |
|||
npm run build # Production build (utoopack, Turbopack-based) |
|||
npm run preview # Preview production build on port 8000 |
|||
npm run preview:build # Build and preview on port 8000 |
|||
npm run deploy # Build and deploy to GitHub Pages (gh-pages branch) |
|||
npm run analyze # Bundle size analysis |
|||
|
|||
# Lint & Type Check |
|||
npm run lint # Biome lint + tsc --noEmit |
|||
npm run biome # Biome check --write (auto-fix) |
|||
npm run tsc # Type check only (tsc --noEmit) |
|||
|
|||
# Test |
|||
npm run test # Run all Jest tests |
|||
npm run test:coverage # Jest with coverage |
|||
npm run test:update # Update test snapshots |
|||
# Run a single test: npx jest src/pages/user/login/login.test.tsx |
|||
|
|||
# Code Generation |
|||
npm run openapi # Regenerate services from config/oneapi.json (overwrites src/services/) |
|||
|
|||
# Other |
|||
npm run simple # Irreversible: removes most page blocks for minimal version |
|||
npm run i18n-remove # Remove i18n, replace with zh-CN |
|||
npm run record # Record request data for mock replay |
|||
``` |
|||
|
|||
## Documentation |
|||
|
|||
- `docs/cheatsheet.zh-CN.md` / `docs/cheatsheet.en-US.md` — comprehensive cheatsheet covering routes, layout, data flow, requests, permissions, i18n, styling, and testing with code examples. Rendered in the Welcome page via `@ant-design/x-markdown`. |
|||
|
|||
## Architecture |
|||
|
|||
### Framework: Umi Max |
|||
|
|||
Umi Max (`@umijs/max`) is the meta-framework. It wraps the build pipeline and provides conventions: |
|||
|
|||
- **Build tool**: utoopack (Turbopack-based, Webpack-compatible). Configured via `utoopack` field in `config/config.ts`, supports `module.rules` for custom loaders |
|||
- **Central config**: `config/config.ts` (defineConfig) controls all plugins, theme, proxy, and build settings |
|||
- **Routes**: Defined declaratively in `config/routes.ts`, not convention-based. Each route maps `component` to a file under `src/pages/`. Route `name` auto-maps to `menu.xxx` i18n key. Route `access` field controls menu visibility (unauthorized routes hidden from menu) |
|||
- **Convention files in `src/`**: `app.tsx` (runtime config), `access.ts` (permissions), `global.tsx` (side effects), `loading.tsx` (route transitions), `typings.d.ts` (global types) |
|||
- **Umi plugins** are enabled via config flags in `config/config.ts` (e.g., `model`, `initialState`, `access`, `locale`, `qiankun`) |
|||
|
|||
### Authentication Flow |
|||
|
|||
1. `app.tsx` exports `getInitialState()` → calls `GET /api/currentUser` |
|||
2. If 401 and not on login page → redirect to `/user/login?redirect=...` |
|||
3. `access.ts` defines permissions: `canAdmin` = `currentUser.access === 'admin'` |
|||
4. Routes use `access: 'canAdmin'` in `config/routes.ts` for permission gating |
|||
5. Login mock credentials: `admin`/`ant.design` (admin) or `user`/`ant.design` (user) |
|||
|
|||
### API & Request Layer |
|||
|
|||
- **Auto-generated services** in `src/services/ant-design-pro/` — do NOT edit manually; regenerate with `npm run openapi` |
|||
- **Per-page services**: many pages have co-located `service.ts` files |
|||
- **Request config**: centralized in `src/requestErrorConfig.ts` (error handler, interceptors, base URL). The `request` export in `app.tsx` sets global `RequestConfig` |
|||
- Built-in `request` function from `@umijs/max` — no manual axios wrapping needed |
|||
- Production API: `https://pro-api.ant-design-demo.workers.dev` |
|||
- Dev proxy config: `config/proxy.ts` (keyed by `UMI_ENV`) |
|||
|
|||
### Mock System |
|||
|
|||
- Global mocks in `mock/` (Express-style handlers matching URL patterns like `'GET /api/currentUser'`) |
|||
- Co-located page mocks: `src/pages/**/_mock.ts` (Umi auto-discovers these) |
|||
- `requestRecord.mock.js` is gitignored |
|||
|
|||
### State Management |
|||
|
|||
- **Umi model plugin** (`useModel`): files in `src/models/` auto-register as global hooks. Use `useModel('filename')` in any component |
|||
- **`useModel('@@initialState')`** for global state (currentUser, settings). Initialized by `getInitialState()` in `app.tsx` which runs once on app startup |
|||
- **`useRequest`** from `@umijs/max` for simple data fetching |
|||
- **@tanstack/react-query** for complex server state (e.g., table-list uses `useMutation` + `useQuery`) |
|||
- Most pages use ProTable's built-in `request` prop for data loading |
|||
|
|||
### Styling Systems |
|||
|
|||
1. **Tailwind CSS v4** — entry: `src/tailwind.css`, PostCSS plugin in `postcss.config.js`. Best for layout utilities |
|||
2. **antd-style v4** (`createStyles`) — CSS-in-JS with design token access (`{ token }`). Preferred when consuming theme tokens |
|||
3. **CSS Modules** (`*.module.less` / `*.module.css`) — for component-scoped styles |
|||
4. **Less** (`global.less`) — legacy, only for font-face declarations and base styles |
|||
|
|||
New code should prefer Tailwind for layout, antd-style for theme-aware styles, CSS Modules for component styles. Less is only for legacy global styles. |
|||
|
|||
Dynamic theme: configured in `config/config.ts` under `antd.configProvider.theme.token`. Dev mode `SettingDrawer` allows live theme switching. |
|||
|
|||
### Internationalization |
|||
|
|||
8 locales in `src/locales/` (zh-CN, en-US, zh-TW, ja-JP, pt-BR, id-ID, fa-IR, bn-BD). Pages use `useIntl().formatMessage()` with `id` and `defaultMessage`. Menu labels auto-resolve via route `name` key (e.g., `name: 'login'` → `menu.login`). |
|||
`npm start` (dev+mock), `npm run dev` (no mock), `npm run build` (utoopack), `npm run lint` (Biome+tsc), `npm run test` (Jest), `npx antd lint ./src` (antd-specific checks). |
|||
|
|||
### Layout |
|||
Other: `npm run openapi` (regenerate `src/services/`), `npm run simple` (**irreversible** — commit first), `npm run biome` (auto-fix), `npm run tsc` (type-check only). |
|||
|
|||
ProLayout is configured via the `layout` export in `src/app.tsx` (`RunTimeLayoutConfig`). Layout settings (theme, color, layout mode) in `config/defaultSettings.ts`. Layout modes: `side` (sidebar), `top` (top nav), `mix` (mixed). Routes with `layout: false` (e.g., `/user/*`) render without the ProLayout shell. Use `<PageContainer>` from `@ant-design/pro-components` for page-level headers and breadcrumbs. |
|||
## Critical Rules |
|||
|
|||
### Page Co-location Pattern |
|||
- **Never edit `src/services/ant-design-pro/`** — auto-generated, regenerate with `npm run openapi` |
|||
- **Biome only** — no ESLint, no Prettier. Both `npm run lint` and `npx antd lint ./src` must pass before commit |
|||
- **Always `npx antd info <Component>` before writing antd code** — don't guess APIs from memory |
|||
- **`npm run simple` is irreversible** — always commit/branch first |
|||
- **Conventional commits** required (commitlint enforced) |
|||
- **TypeScript strict** · **Node ≥ 20** · **`package-lock.json`** (not yarn/pnpm) |
|||
- **`.umi` dir is auto-generated** — delete `src/.umi` and restart if dev server acts up |
|||
|
|||
Each page directory contains its own index.tsx, optional service.ts, _mock.ts, data.d.ts (types), and style.ts or CSS files. This is the primary organizational pattern — keep page-specific code with the page. |
|||
## Architecture Essentials |
|||
|
|||
### Cloudflare Worker Backend |
|||
**Config**: `config/config.ts` (defineConfig), `config/routes.ts` (declarative routes). Route `name` → `menu.xxx` i18n key; `access` field gates visibility. |
|||
|
|||
`cloudflare-worker/` is a separate deployable (Hono framework, own `package.json`/`tsconfig.json`). Not an npm workspace — manage independently. Provides the production demo API. |
|||
**Convention files** (`src/`): `app.tsx` (runtime config + `getInitialState`), `access.ts` (permissions), `global.tsx` (side effects), `loading.tsx`, `typings.d.ts`. |
|||
|
|||
```bash |
|||
cd cloudflare-worker |
|||
npm run dev # Local dev (wrangler dev) |
|||
npm run deploy # Deploy to Cloudflare (wrangler deploy) |
|||
``` |
|||
**Auth**: `getInitialState()` → `GET /api/currentUser`; 401 → redirect login. `access.ts`: `canAdmin = currentUser.access === 'admin'`. Mock creds: `admin`/`ant.design` or `user`/`ant.design`. |
|||
|
|||
## Ant Design CLI |
|||
**State**: `useModel('filename')` for global hooks (`src/models/`). `useModel('@@initialState')` for currentUser/settings. ProTable `request` prop for most data loading. `@tanstack/react-query` for complex server state. |
|||
|
|||
`@ant-design/cli` (antd) is installed as a dev dependency. It provides offline antd component metadata and project analysis. Run via `npx antd`. |
|||
**Styling priority**: Tailwind CSS v4 (layout) → antd-style v4 / `createStyles` (theme tokens) → CSS Modules → Less (legacy only). |
|||
|
|||
- **Always query before writing antd code** — use `npx antd info <Component>` to check props/APIs rather than guessing from memory |
|||
- `npx antd demo <Component> <name>` — get working demo code |
|||
- `npx antd token <Component>` — check design tokens |
|||
- `npx antd semantic <Component>` — check semantic classNames |
|||
- `npx antd lint ./src` — find deprecated or problematic antd usage. **Must pass with zero errors and warnings before committing** |
|||
- `npx antd doctor` — diagnose project configuration issues |
|||
- `npx antd migrate <v1> <v2>` — migration checklist between versions |
|||
- Always use `--format json` for structured output |
|||
**Request**: built-in `request` from `@umijs/max`, configured in `src/requestErrorConfig.ts`. Per-page `service.ts` for non-generated APIs. |
|||
|
|||
The CLI also supports MCP server mode: `npx antd mcp` (for IDE integrations). |
|||
**i18n**: 8 locales in `src/locales/`. `useIntl().formatMessage({ id, defaultMessage })`. |
|||
|
|||
## Key Conventions |
|||
**Mock**: `mock/` (global) + `src/pages/**/_mock.ts` (co-located). Express-style handlers. |
|||
|
|||
- **Biome** replaces ESLint + Prettier. Config in `biome.json`. Pre-commit hook runs `lint-staged` with Biome. |
|||
- **Commit messages**: must follow conventional commits (`commitlint` with `@commitlint/config-conventional`). |
|||
- **TypeScript strict mode** enabled. Path aliases: `@/*` → `./src/*`, `@@/*` → `./src/.umi/*`. |
|||
- **Node >= 20** required. |
|||
- **Markdown as raw strings**: `config/md-raw-loader.cjs` lets `.md` files be imported as strings (used in Welcome/cheatsheet pages with `@ant-design/x-markdown`). |
|||
- **Auto-generated code in `src/services/`** is excluded from Biome linting |
|||
- **Adding a new page**: 1) Create component in `src/pages/` 2) Add route in `config/routes.ts` 3) Add menu translation in `src/locales/` (route `name` maps to `menu.xxx` i18n key) |
|||
- **Adding global state**: Create a file in `src/models/` exporting a custom Hook, use `useModel('filename')` in components |
|||
- **Access control**: Route-level via `access` field in routes; component-level via `<Access accessible={...}>` or `useAccess()` hook from `@umijs/max` |
|||
**Cloudflare Worker**: `cloudflare-worker/` — separate Hono app, own `package.json`, not an npm workspace. |
|||
|
|||
## Gotchas & Troubleshooting |
|||
## Page Co-location |
|||
|
|||
- **`.umi` directory**: Auto-generated by Umi. If dev server behaves unexpectedly, delete `src/.umi` and restart |
|||
- **Port 8000 in use**: Kill the process (`lsof -ti:8000 | xargs kill`) or use `PORT=3000 npm start` to change it |
|||
- **Mock not updating**: Umi usually auto-discovers `mock/` and `src/pages/**/_mock.ts` changes. If a new file isn't recognized, try restarting the dev server |
|||
- **Biome + antd lint**: Both must pass before committing. `npm run lint` runs Biome + tsc; `npx antd lint ./src` runs separately. Do not install ESLint or Prettier — this project uses Biome only |
|||
- **`src/services/` is auto-generated**: Never edit manually. Run `npm run openapi` to regenerate |
|||
- **`npm run simple` is irreversible**: Always commit or branch before running it |
|||
- **Lock file**: Uses `package-lock.json`. If deps break, delete `node_modules` and reinstall |
|||
Each page dir: `index.tsx`, optional `service.ts`, `_mock.ts`, `data.d.ts`, style files. Keep page-specific code with the page. |
|||
Loading…
Reference in new issue