diff --git a/README.md b/README.md index 22a58e4..1414b8f 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ Scaffolding CLI: - URL-synced table state (pagination, sorting, search) - Dark mode theme switching - Mock-first local development (no backend required) +- Modular API layer (`defineApi` per domain, Zod schemas, shared `API_PREFIX`) - Typed API boundaries and reusable CRUD patterns - React 19 + Ant Design 6 + TanStack Router/Query + Zustand + Zod - Optional Lingui-based i18n workflow (`with-lingui`) @@ -48,15 +49,15 @@ pnpm dlx init-antd-admin@latest my-app --example with-lingui --skip-install ### Common options -| Option | Description | -| ---------------------------- | -------------------------------- | -| `[project-directory]` | Target folder | -| `-e, --example ` | -| `--example-path ` | Subpath inside remote repository | -| `-m, --package-manager ` | `npm` / `pnpm` / `yarn` / `bun` | -| `--skip-install` | Skip dependency install | -| `--skip-transforms` | Skip rewrite transforms | -| `--no-git` | Skip git initialization | +| Option | Description | +| ---------------------------- | ------------------------------------------ | +| `[project-directory]` | Target folder | +| `-e, --example ` | Template name (`basic`, `with-lingui`) or URL | +| `--example-path ` | Subpath inside remote repository | +| `-m, --package-manager ` | `npm` / `pnpm` / `yarn` / `bun` | +| `--skip-install` | Skip dependency install | +| `--skip-transforms` | Skip rewrite transforms | +| `--no-git` | Skip git initialization | For detailed CLI behavior, see `[packages/create/README.md](./packages/create/README.md)`. diff --git a/apps/basic/README.md b/apps/basic/README.md index 7f3864f..ceb548a 100644 --- a/apps/basic/README.md +++ b/apps/basic/README.md @@ -35,7 +35,7 @@ Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built | Icons | [lucide-react](https://lucide.dev/guide/packages/lucide-react) | | API Mocking | [MSW 2.x](https://mswjs.io) (Service Worker based) | | E2E Testing | [Playwright](https://playwright.dev) | -| Language | TypeScript 5.9 (strict mode) | +| Language | TypeScript (strict mode) | ## Features @@ -44,6 +44,7 @@ Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built - **URL-First State** — Table search params (page, pageSize, keyword, sort) synced to URL - **Default locale** — UI copy in plain strings (English by default); Ant Design `ConfigProvider` uses `en_US`. - **Dark Mode** — One-click toggle with Ant Design theme algorithm +- **Modular API layer** — `defineApi` modules under `src/api//`, shared Zod helpers, single `API_PREFIX` - **Full Type Safety** — Zod schemas validate API boundaries at runtime where used - **Zero-Config Mocking** — MSW intercepts API calls in development, no backend needed @@ -96,7 +97,7 @@ pnpm run test:unit ```bash pnpm run test:e2e -pnpm run test:e2e:core +pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # core flows only pnpm run test:e2e:ui # interactive UI mode ``` @@ -106,7 +107,12 @@ pnpm run test:e2e:ui # interactive UI mode AGENTS.md # Agent rules (frontend/api/testing/refactor) .agents/skills/add-resource/ # CRUD scaffold checklist (Skill) src/ -├── api/ # request.ts, shared/, auth/, users/, … (defineApi per module) +├── api/ # HTTP + contracts (see “API layer” below) +│ ├── request.ts # axios, defineApi, token refresh, envelope unwrap +│ ├── schemas.ts # deprecated barrel; prefer @/api/shared and module schemas +│ ├── shared/ # API_PREFIX, pagination, params, menu, envelope helpers +│ ├── auth/ # paths, schemas, login/register/hydrateSession +│ └── users/ # schemas, listUsers CRUD, userQueryKeys, path constants ├── components/ # Reusable UI primitives and layout shells │ ├── Layout/ # MainLayout, Header, Sidebar, UserMenu, AppFooter │ ├── DataTable/ # Shared table frame/skeleton/empty state @@ -158,6 +164,19 @@ e2e/ # Playwright E2E suites └── url-state.spec.ts ``` +## API layer + +Data flow: **Zod schemas → `defineApi` in `src/api//index.ts` → routes/components call resource functions** (never axios or `@/api/request` directly). + +| Piece | Role | +| ----------------- | ------------------------------------------------------------------------------------------------- | +| `request.ts` | Shared HTTP client, `{ code, data, message }` handling, 401 refresh | +| `shared/` | `API_PREFIX` (`/api`), pagination/query helpers, shared menu types | +| `auth/`, `users/` | Domain schemas + `defineApi` exports; MSW handlers import the same path constants | +| `schemas.ts` | Compatibility re-exports; new code should import from `@/api/shared` and `@/api//schemas` | + +Change the REST prefix in one place: `src/api/shared/prefix.ts` (`API_PREFIX`). + ## Language User-facing copy lives in components and routes as plain strings. **Default language is English**; Ant Design is wired to `en_US` in `__root.tsx`. This template does not include a locale switcher or translation catalogs—you can add your own i18n library or start from the [`with-lingui`](../with-lingui/) template for LinguiJS (en + zh). diff --git a/apps/with-lingui/README.md b/apps/with-lingui/README.md index 3405223..290d54f 100644 --- a/apps/with-lingui/README.md +++ b/apps/with-lingui/README.md @@ -25,7 +25,7 @@ Balanced admin scaffold: i18n (Lingui), MSW mocks, minimal RBAC, full CRUD, and | Icons | [lucide-react](https://lucide.dev/guide/packages/lucide-react) | | API Mocking | [MSW 2.x](https://mswjs.io) (Service Worker based) | | E2E Testing | [Playwright](https://playwright.dev) | -| Language | TypeScript 5.9 (strict mode) | +| Language | TypeScript (strict mode) | ## Features @@ -34,6 +34,7 @@ Balanced admin scaffold: i18n (Lingui), MSW mocks, minimal RBAC, full CRUD, and - **URL-First State** — Table search params (page, pageSize, keyword, sort) synced to URL - **i18n** — LinguiJS with English (`en`) and Chinese (`zh`); Ant Design locales wired in root - **Dark Mode** — One-click toggle with Ant Design theme algorithm +- **Modular API layer** — `defineApi` modules under `src/api//`, shared Zod helpers, single `API_PREFIX` - **Full Type Safety** — Zod schemas validate API boundaries at runtime where used - **Zero-Config Mocking** — MSW intercepts API calls in development, no backend needed @@ -86,7 +87,7 @@ pnpm run test:unit ```bash pnpm run test:e2e -pnpm run test:e2e:core +pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # core flows only pnpm run test:e2e:ui # interactive UI mode ``` @@ -100,7 +101,7 @@ vp exec lingui extract -- --clean vp exec lingui compile # CI-oriented check: extract + ensure no pending locale diff -pnpm run i18n:extract && git diff --exit-code -- src/locales +pnpm run i18n:check ``` ## Project Structure @@ -109,7 +110,12 @@ pnpm run i18n:extract && git diff --exit-code -- src/locales AGENTS.md # Agent rules (frontend/api/testing/refactor) .agents/skills/add-resource/ # CRUD scaffold checklist (Skill) src/ -├── api/ # request.ts, shared/, auth/, users/, … (defineApi per module) +├── api/ # HTTP + contracts (see “API layer” below) +│ ├── request.ts # axios, defineApi, token refresh, envelope unwrap +│ ├── schemas.ts # deprecated barrel; prefer @/api/shared and module schemas +│ ├── shared/ # API_PREFIX, pagination, params, menu, envelope helpers +│ ├── auth/ # paths, schemas, login/register/hydrateSession +│ └── users/ # schemas, listUsers CRUD, userQueryKeys, path constants ├── components/ # Reusable UI primitives and layout shells │ ├── Layout/ # MainLayout, Header, Sidebar, UserMenu, AppFooter │ ├── DataTable/ # Shared table frame/skeleton/empty state @@ -166,9 +172,13 @@ e2e/ # Playwright E2E suites ``` +## API layer + +Same layout as [`apps/basic`](../basic/): **schemas → `defineApi` in `src/api//index.ts` → UI imports `@/api/users`, `@/api/auth`, etc.** Transport stays in `request.ts`; path constants (`API_PREFIX`, `AUTH_ENDPOINTS`, `USERS_PATH`) are shared with MSW handlers. + ## Internationalization (i18n) -The project uses [LinguiJS](https://lingui.dev) with compile-time macros. Locales: `**en**` (source) and `**zh**`. +The project uses [LinguiJS](https://lingui.dev) with compile-time macros. Locales: **en** (source) and **zh**. ### Workflow @@ -181,7 +191,7 @@ Ant Design strings follow the active locale via `ConfigProvider` in `__root.tsx` ## Extending the template -- **New CRUD resource:** Follow `.agents/skills/add-resource/SKILL.md` (mirror `users`), then `pnpm run i18n:extract && pnpm run i18n:compile`, and `pnpm exec vp check --no-fmt`. +- **New CRUD resource:** Follow `.agents/skills/add-resource/SKILL.md` (mirror `users`), then `pnpm run i18n:extract && pnpm run i18n:compile`, and `pnpm run check`. - **Real backend:** Point `VITE_API_BASE_URL` in env and disable or remove MSW in `main.tsx` when you no longer need mocks. - **Drop i18n:** Remove Lingui packages, vite/swc plugins, and replace `t` macros with plain strings (larger refactor).