# Ant Design Pro — User Guide

Ant Design Pro is an **out-of-the-box UI solution for enterprise applications**, shipped as a production-ready React boilerplate. Rather than a library you install, it is a complete starter project you **clone, run, and build your own admin application on top of** — a working app with authentication, a configurable layout, a dozen ready-made page templates, internationalization, mock data, and a demo backend already wired together.

This guide is for the developer who is starting a new enterprise dashboard, internal tool, or admin console and wants a solid, batteries-included foundation. It covers getting the project running, touring every template page, customizing the parts you'll touch first, and shipping a production build.

> [!NOTE]
> Ant Design Pro is a **scaffold**, not an installable package. There is no `npm install ant-design-pro`. You clone the repository, make it your own, and the demo pages become reference examples or starting points for your real pages.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Requirements](#2-requirements)
3. [Installation](#3-installation)
4. [Running the Project](#4-running-the-project)
5. [Logging In (Demo Credentials)](#5-logging-in-demo-credentials)
6. [The Template Pages](#6-the-template-pages)
7. [Everyday Development Tasks](#7-everyday-development-tasks)
8. [Customizing the Layout & Theme](#8-customizing-the-layout--theme)
9. [Internationalization](#9-internationalization)
10. [The AI Assistant Page](#10-the-ai-assistant-page)
11. [Building & Deploying](#11-building--deploying)
12. [Simple Mode: Stripping to a Minimal Template](#12-simple-mode-stripping-to-a-minimal-template)
13. [How It Works (Concepts)](#13-how-it-works-concepts)
14. [Command Reference](#14-command-reference)
15. [Troubleshooting](#15-troubleshooting)
16. [FAQ](#16-faq)

---

## 1. Quick Start

Get a full Ant Design Pro app running locally in four commands.

```bash
git clone --depth=1 https://github.com/ant-design/ant-design-pro.git myapp
cd myapp
npm install
npm start
```

The development server starts and opens `http://localhost:8000`. You will land on the login page. Sign in with the demo account (`admin` / `ant.design`) and you'll have a fully working admin shell — sidebar navigation, theme switcher, language switcher, and every template page populated with mock data.

> [!TIP]
> Use `--depth=1` when cloning. You want the latest template, not the project's entire commit history. The clone becomes *your* project, so a shallow clone keeps it lean and lets you start your own Git history.

```text
$ npm start

  App listening at:
  - Local:   http://localhost:8000
  - Network: http://192.168.x.x:8000

  ready in 3.4s
```

> [!IMPORTANT]
> After cloning, this is **your** codebase. You are expected to edit `config/routes.ts`, delete demo pages you don't need, and replace the mock API with your real backend. Nothing here is off-limits.

---

## 2. Requirements

Ant Design Pro v6 targets a modern toolchain. Verify your environment before installing.

| Requirement | Minimum | Notes |
|---|---|---|
| **Node.js** | `>= 22.0.0` | Declared in `package.json` `engines`. The cheatsheet badge says `>= 20`; the package manifest enforces `>= 22`. Use 22 LTS or newer. |
| **Package manager** | npm (bundled with Node) | Examples use `npm`. `pnpm` and `yarn` also work. |
| **Operating system** | macOS, Linux, Windows 11 | Fully cross-platform. See the Windows note below. |
| **Modern browser** | Edge / Firefox / Chrome / Safari (last 2 versions) | `browserslist` is set to `defaults`. No IE support. |

> [!WARNING]
> On **Windows 11**, an early v6 setup could fail with `Can't resolve 'tailwindcss'` (reported in issues [#11747](https://github.com/ant-design/ant-design-pro/issues/11747) and [#11818](https://github.com/ant-design/ant-design-pro/issues/11818)). If you hit it, delete `node_modules` and `package-lock.json`, then reinstall. See [Troubleshooting](#15-troubleshooting).

To check your versions:

```bash
node --version
npm --version
```

```text
v22.11.0
10.9.0
```

---

## 3. Installation

### Step 1 — Get the code

=== "Clone (recommended)"

    ```bash
    git clone --depth=1 https://github.com/ant-design/ant-design-pro.git myapp
    cd myapp
    ```

=== "Download a release"

    Download a tagged release archive from the [Releases page](https://github.com/ant-design/ant-design-pro/releases), extract it, and `cd` into the folder.

### Step 2 — Install dependencies

```bash
npm install
```

This installs the application dependencies (React 19, antd 6, ProComponents, UmiJS Max, React Query, and friends) plus the dev toolchain (Biome, Vitest, the antd CLI, the OpenAPI plugin).

```text
added 1043 packages in 41s
```

> [!NOTE]
> Installation also runs a `prepare` script that sets up Git hooks via Husky and initializes the UmiJS Max temp directory (`src/.umi`). This is normal and only needs to happen once.

### Step 3 — Start your own Git history (optional but recommended)

Because the clone is now your project, it's good practice to detach it from the template's history:

```bash
rm -rf .git
git init
git add -A
git commit -m "chore: initial commit from Ant Design Pro v6"
```

---

## 4. Running the Project

Ant Design Pro ships several start scripts, each wiring up a different environment and data source. The two you'll use most are `npm start` (mock data) and `npm run start:no-mock` (your real backend).

| Command | Environment | Data source | When to use |
|---|---|---|---|
| `npm start` | `dev` | **Mock data** | Default. Explore the template with realistic fake data. |
| `npm run dev` | `dev` | No mock | Develop against a proxied backend. |
| `npm run start:no-mock` | `dev` | No mock | Same as above; explicit `MOCK=none`. |
| `npm run start:pre` | `pre` | No mock | Point at a pre-production backend. |
| `npm run start:test` | `test` | No mock | Point at a test backend (the public demo Worker). |

```bash
npm start
```

```text
  ready in 3.4s
  - Local:   http://localhost:8000
```

> [!TIP]
> The first run is the slowest because the bundler warms its cache. Subsequent starts and hot reloads are fast. If startup feels sluggish overall (community question [#11795](https://github.com/ant-design/ant-design-pro/issues/11795)), make sure you're on the required Node version and that no antivirus is scanning `node_modules` on Windows.

### Where does the data come from?

In the **default `npm start` (mock) mode**, requests to `/api/*` are answered locally by mock files (`src/pages/**/_mock.ts` and the `mock/` directory) — no backend needed. In the **test environment**, requests are proxied to the public demo backend, a Cloudflare Worker at `https://pro-api.ant-design-demo.workers.dev`. You configure your own proxy targets in `config/proxy.ts`.

---

## 5. Logging In (Demo Credentials)

The first screen is the login page (`/user/login`). It offers two tabs — **Account password** and **Phone number** — both backed by the demo mock.

**Account login:**

| Field | Demo value |
|---|---|
| Username | `admin` or `user` |
| Password | `ant.design` |

**Phone login:** enter any 11-digit number starting with `1`, click **Get verification code**, then enter the code `1234`.

> [!NOTE]
> In demo mode the backend **always grants an admin session** regardless of what you type — the mock login endpoint returns `currentAuthority: "admin"`. The username/password fields exist to demonstrate the `LoginForm` component and validation, not real authentication. Replace this with your real auth flow before going to production. See the [Admin Guide](/guides/ant-design/ant-design-pro/admin-guide/) for how authentication and permissions are wired.

The difference between `admin` and `user` matters for the **Admin** page: only an `admin`-access session sees the **Admin → Sub-Page** menu item, because that route is guarded by `access: 'canAdmin'`.

> [!TIP]
> Sign in as `admin` to see every menu item, including the access-controlled Admin page. This is the quickest way to understand how route-level permissions hide and show navigation.

---

## 6. The Template Pages

Every page you see in the sidebar is a ready-made template under `src/pages/`, registered in `config/routes.ts`. They exist to be copied, adapted, or deleted. Here is the complete catalog, grouped exactly as they appear in the navigation menu.

### Welcome

`/welcome` — The landing page. Renders the project cheatsheet (Markdown) alongside quick links to learn UmiJS, Ant Design, and ProComponents. A good model for any "getting started" or documentation page inside your own app.

### Dashboard

| Page | Path | What it demonstrates |
|---|---|---|
| **Analysis** | `/dashboard/analysis` | A rich analytics dashboard — sales charts, visit trends, ranking lists, a proportion pie, and a keyword search funnel. Built with `@ant-design/plots`. |
| **Monitor** | `/dashboard/monitor` | A real-time monitoring screen with gauges, an activity map (D3 + TopoJSON), and live counters. |
| **Workplace** | `/dashboard/workplace` | A personalized home page — greeting, quick links, activity feed, and team list. |

### Form

| Page | Path | What it demonstrates |
|---|---|---|
| **Basic Form** | `/form/basic-form` | A standard single-column form with validation. |
| **Step Form** | `/form/step-form` | A multi-step wizard (e.g. a transfer flow) with a progress indicator. |
| **Advanced Form** | `/form/advanced-form` | A complex form with grouped sections and an editable inline table. |

### List

| Page | Path | What it demonstrates |
|---|---|---|
| **Search Table** | `/list/table-list` | The flagship CRUD table: search, sort, pagination, row selection, batch actions, create/update modals, and a detail drawer. Built on `ProTable`. |
| **Basic List** | `/list/basic-list` | A list with inline operations and an add/edit modal. |
| **Card List** | `/list/card-list` | A responsive grid of cards. |
| **Search List — Articles / Projects / Applications** | `/list/search/articles`, `/projects`, `/applications` | Three search-result layouts (article feed, project cards, application grid) with a shared filter bar. |

### Profile

| Page | Path | What it demonstrates |
|---|---|---|
| **Basic Profile** | `/profile/basic` | A detail page with descriptions and an itemized table (e.g. an order/return record). |
| **Advanced Profile** | `/profile/advanced` | A header with tabs, status steps, and multiple data tables. |

### Result

| Page | Path | What it demonstrates |
|---|---|---|
| **Success** | `/result/success` | A success confirmation screen with next-step actions. |
| **Fail** | `/result/fail` | A failure screen with an error explanation. |

### Exception

| Page | Path | What it demonstrates |
|---|---|---|
| **403** | `/exception/403` | "Forbidden" page. |
| **404** | `/exception/404` | "Not found" page (also the catch-all for unmatched routes). |
| **500** | `/exception/500` | "Server error" page. |

### Account

| Page | Path | What it demonstrates |
|---|---|---|
| **Account Center** | `/account/center` | A user profile hub with tabs for articles, applications, and projects. |
| **Account Settings** | `/account/settings` | A settings page with sub-sections for basic info, security, binding, and notifications. |

### AI Assistant

`/chatbot` — A complete chat interface built with [Ant Design X](https://x.ant.design/). Streaming responses, conversation history, a "thinking" panel, and Markdown rendering. See [The AI Assistant Page](#10-the-ai-assistant-page).

### User (no layout)

| Page | Path | What it demonstrates |
|---|---|---|
| **Login** | `/user/login` | Account + phone login tabs with validation and social-login icons. |
| **Register** | `/user/register` | A registration form. |
| **Register Result** | `/user/register-result` | A post-registration confirmation screen. |

> [!TIP]
> The **Search Table** page (`/list/table-list`) is the single best page to study. It exercises `ProTable` end to end — server-side search and pagination, sorting, multi-row selection with a batch toolbar, create/update forms, and a read-only detail drawer. If you build admin CRUD screens, start here.

---

## 7. Everyday Development Tasks

These are the customizations you'll perform constantly. Each maps to a small, well-defined edit.

### Add a new page

1. **Create the component** at `src/pages/my-page/index.tsx`:

   ```tsx
   import { PageContainer } from '@ant-design/pro-components';

   const MyPage: React.FC = () => (
     <PageContainer>
       <h1>My Page</h1>
     </PageContainer>
   );

   export default MyPage;
   ```

2. **Register the route** in `config/routes.ts`:

   ```ts
   {
     path: '/my-page',
     name: 'my-page',   // maps to the menu.my-page i18n key
     icon: 'file',
     component: './my-page',
   }
   ```

3. **Add the menu label** in `src/locales/en-US/menu.ts` (and other locales you support):

   ```ts
   'menu.my-page': 'My Page',
   ```

That's it — UmiJS picks up the route, renders the sidebar item, and code-splits the page automatically.

> [!NOTE]
> The `component` path is relative to `src/pages`, so `./my-page` resolves to `src/pages/my-page/index.tsx`. The `name` field is **not** the displayed text — it's an i18n key. The visible label comes from `menu.<name>` in your locale files.

### Remove a demo page you don't need

1. Delete its folder under `src/pages/` (e.g. `src/pages/dashboard/`).
2. Remove its entry (and any redirects to it) from `config/routes.ts`.
3. Optionally remove its menu keys from `src/locales/*/menu.ts`.

> [!TIP]
> If you want to clear out *most* of the demos at once, use [Simple Mode](#12-simple-mode-stripping-to-a-minimal-template) instead of deleting folders by hand.

### Call your backend

The project uses a unified `request` helper from UmiJS Max. The generated service layer lives in `src/services/ant-design-pro/`:

```tsx
import { request } from '@umijs/max';

// GET with query params
const data = await request('/api/users', { params: { page: 1 } });

// POST with a body
await request('/api/users', { method: 'POST', data: { name: 'test' } });
```

For server state (caching, refetching, mutations), the project standardizes on **React Query**:

```tsx
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
  queryKey: ['user', id],
  queryFn: () => getUser(id),
});
```

### Point at your real API

Open `config/proxy.ts` and set the target for your environment. The `dev` block is commented out by default; uncomment and edit it:

```ts
export default {
  dev: {
    '/api/': {
      target: 'http://localhost:8080',
      changeOrigin: true,
    },
  },
};
```

Then run `npm run dev` (no mock) so requests hit the proxy instead of the local mocks.

> [!WARNING]
> Proxies only work in the **development** server. They have no effect in a production build. In production, your built static files call whatever absolute `baseURL` is configured in `src/app.tsx`, or same-origin `/api/*` paths served behind your own reverse proxy.

### Add or change mock data

Mock responses live in two places, both auto-registered by UmiJS:

- **Global mocks:** files in `mock/` (e.g. `mock/user.ts`).
- **Page-level mocks:** `src/pages/<page>/_mock.ts`.

```ts
// mock/user.ts
export default {
  'GET /api/currentUser': { name: 'Serati Ma', access: 'admin' },
};
```

---

## 8. Customizing the Layout & Theme

The application shell — sidebar, header, page container — is **ProLayout**, configured in `config/defaultSettings.ts`. These are the settings you'll change first.

```ts
// config/defaultSettings.ts
export default {
  navTheme: 'light',          // 'light' | 'realDark'
  colorPrimary: '#1677ff',    // brand/primary color
  layout: 'mix',              // 'side' | 'top' | 'mix'
  contentWidth: 'Fluid',      // 'Fluid' | 'Fixed'
  fixedHeader: false,
  fixSiderbar: true,
  colorWeak: false,
  title: 'Ant Design Pro',
  logo: 'https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg',
};
```

| Setting | Values | Effect |
|---|---|---|
| `navTheme` | `light`, `realDark` | Light or dark navigation chrome. |
| `colorPrimary` | any hex color | The brand/accent color used across antd components. |
| `layout` | `side`, `top`, `mix` | Sidebar nav, top nav, or a combined header + sidebar. |
| `contentWidth` | `Fluid`, `Fixed` | Full-width content vs. a centered fixed-width column. |
| `fixedHeader` | `true`, `false` | Pin the header on scroll. |
| `fixSiderbar` | `true`, `false` | Pin the sidebar on scroll. |
| `title` | string | The product name shown in the header and browser tab. |
| `logo` | URL | The logo image in the header. |

### Preview changes live with the Setting Drawer

In development, a **gear icon** floats at the right edge of every page. Click it to open the **Setting Drawer**, where you can toggle the theme, layout mode, primary color, and more — in real time, without editing files. Once you find settings you like, copy them into `config/defaultSettings.ts` to make them permanent.

> [!TIP]
> The Setting Drawer is a development convenience for *finding* the look you want. It does not persist your choices to disk — `defaultSettings.ts` is the source of truth for what ships.

### Three ways to style

The template supports three styling approaches that coexist by design:

| Approach | Use it for | Example |
|---|---|---|
| **Tailwind CSS v4** | Layout, spacing, utility tweaks | `className="flex items-center gap-4 p-6"` |
| **antd-style** (CSS-in-JS) | Component styles that need theme tokens | `createStyles(({ token, css }) => ...)` |
| **CSS Modules** | Scoped component styles | `import styles from './x.module.less'` |

> [!NOTE]
> The recommended priority is **Tailwind for layout → antd-style when you need theme tokens → CSS Modules for the rest**. Plain global Less (`src/global.less`) is reserved for legacy global overrides only.

---

## 9. Internationalization

Ant Design Pro ships with a built-in i18n solution and **eight bundled locales** out of the box.

| Locale | Language |
|---|---|
| `zh-CN` | 简体中文 (default) |
| `zh-TW` | 繁體中文 |
| `en-US` | English |
| `ja-JP` | 日本語 |
| `pt-BR` | Português |
| `id-ID` | Bahasa Indonesia |
| `fa-IR` | فارسی |
| `bn-BD` | বাংলা |

Users switch language from the **globe icon** in the header. The default locale is `zh-CN`; set your own default in `config/config.ts`:

```ts
locale: {
  default: 'zh-CN',     // change to 'en-US' to default to English
  antd: true,           // also localize antd's own components
  baseNavigator: true,  // honor the browser's language on first load
},
```

### Using translations in your code

```tsx
import { useIntl, FormattedMessage } from '@umijs/max';

// Hook form
const intl = useIntl();
const label = intl.formatMessage({ id: 'menu.welcome' });

// Component form
<FormattedMessage id="menu.welcome" />
```

Translation files live under `src/locales/<locale>/`, split by area: `menu.ts`, `pages.ts`, `component.ts`, `globalHeader.ts`, `settings.ts`, `settingDrawer.ts`, and `network.ts`.

> [!TIP]
> Don't need multiple languages? Set `default` to your one locale and delete the locale folders you don't use. To strip the i18n wrappers from the codebase entirely, run `npm run i18n-remove` (it inlines the `zh-CN` strings).

---

## 10. The AI Assistant Page

New in v6, the **AI Assistant** page (`/chatbot`) is a complete, streaming chat UI built with [Ant Design X](https://x.ant.design/) — Ant Design's component suite for AI interfaces.

It demonstrates:

- A **conversation sidebar** with grouped history (Today / Yesterday / Earlier), creation, and per-conversation delete.
- **Streaming responses** with a typewriter effect and live Markdown rendering.
- A **"thinking" panel** that surfaces the model's `<think>...</think>` reasoning separately from its answer.
- A **message composer** (`Sender`) with Enter-to-send and a cancel/abort control.

Out of the box it talks to a public demo model endpoint (GLM-4.5-flash) using server-sent events. To point it at your own model, set the `CHAT_API_URL` environment variable:

```bash
CHAT_API_URL=https://your-host/v1/chat npm start
```

> [!NOTE]
> The chat service uses an OpenAI-compatible streaming provider. If your model server speaks the OpenAI chat-completions protocol with SSE streaming, it will work by just changing `CHAT_API_URL`. The page is a reference implementation — adapt the conversation state and parsing to your product's needs.

> [!CAUTION]
> The default endpoint is a **public demo** meant for trying the UI. Do not send sensitive data to it, and replace it with your own model gateway before shipping.

---

## 11. Building & Deploying

### Build a production bundle

```bash
npm run build
```

This produces a fully static site in the `dist/` directory.

```text
  building...
  ✓ built in 18.2s
  output: dist/
```

### Preview the build locally

```bash
npm run preview
```

This serves the contents of `dist/` on `http://localhost:8000` so you can sanity-check the production output before deploying. (`npm run preview:build` builds first, then previews.)

### Deploy

Because the output is static files, you can host it anywhere — Nginx, a CDN, an object store with static hosting, GitHub Pages, Vercel, Netlify, or Cloudflare Pages.

=== "Any static host"

    Copy the contents of `dist/` to your web root.

    ```bash
    npm run build
    # then upload ./dist to your server / bucket / CDN
    ```

=== "GitHub Pages (built-in)"

    ```bash
    npm run deploy
    ```

    This runs a production build and publishes `dist/` to the `gh-pages` branch automatically.

> [!IMPORTANT]
> Deploying under a sub-path (e.g. `https://example.com/admin/`) instead of the domain root? Set `publicPath` in `config/config.ts` to match (e.g. `'/admin/'`), or asset URLs will break. The default is `'/'` (root).

> [!WARNING]
> The dev proxy in `config/proxy.ts` does **not** ship with the build. In production, your app must reach your API through an absolute `baseURL` (configured in `src/app.tsx`) or via same-origin `/api/*` paths served behind your own reverse proxy. There is no "preview" backend in your deployed app unless you provide one.

---

## 12. Simple Mode: Stripping to a Minimal Template

The full template includes every demo page so you can learn from them. Once you understand the structure, you can strip it down to a bare login + layout skeleton with one command.

```bash
# 1. Commit first — this is irreversible.
git add -A && git commit -m "chore: save before simple"

# 2. Strip demo pages and unused dependencies.
npm run simple

# 3. Refresh dependencies.
npm install
```

`npm run simple` will:

- Delete the demo page directories (dashboard, form, list/*, profile, result, exception, account, etc.).
- Remove the extra page-level mock files.
- Replace `config/routes.ts` with the minimal `routes.simple.ts` (just Login, Welcome, an Admin sub-page, and a table list).
- Remove demo-only dependencies (such as the charts library) from `package.json`.

> [!CAUTION]
> **This operation is irreversible** and permanently deletes files. Always commit (or otherwise back up) your code first so you can `git revert` if you change your mind. (Recommended workflow: explore in full mode, then switch to simple mode when you're ready to build for real.)

---

## 13. How It Works (Concepts)

You can be productive without this section, but understanding the moving parts makes customization obvious. For the deep architecture, see the [Admin Guide](/guides/ant-design/ant-design-pro/admin-guide/).

### Built on UmiJS Max

Ant Design Pro is a [UmiJS Max](https://umijs.org/) application. Max is an "enterprise-grade" React framework that bundles routing, data flow, request handling, access control, i18n, and layout into a single configurable preset. Most of what the template does — the sidebar menu, the login redirect, the permission checks — is Max plugin behavior driven by `config/config.ts`, not custom code you have to maintain.

### Routes are the feature map

`config/routes.ts` is the single source of truth for what pages exist and how the menu is structured. Each entry maps a URL `path` to a page `component`, and its `name` to a menu label. Nesting routes creates nested menu groups. Adding `access: 'canAdmin'` to a route hides it from users who lack that permission.

### Convention-based pages

You don't register page components anywhere except the route config. UmiJS code-splits each route automatically, so every page is its own lazy-loaded chunk — the app stays fast as it grows.

### Permissions flow from the logged-in user

On startup, the app fetches the current user (`getInitialState` in `src/app.tsx`) and computes a set of permission flags in `src/access.ts` (e.g. `canAdmin`). Routes and components consult those flags to show or hide themselves. If the user fetch fails, the app redirects to login.

### Mock-first development

Until you wire up a backend, the app runs entirely on mock data, so you can build and demo UI without any server. Swap in your real API by configuring the proxy and turning mocks off.

---

## 14. Command Reference

Every script from `package.json`, with what it does.

| Command | Description |
|---|---|
| `npm start` | Start the dev server in `dev` env **with mock data** (the default). |
| `npm run dev` | Start the dev server in `dev` env **without mock**. |
| `npm run start:no-mock` | Start without mock (`MOCK=none`). |
| `npm run start:pre` | Start against the `pre` (pre-production) environment, no mock. |
| `npm run start:test` | Start against the `test` environment (public demo backend), no mock. |
| `npm run build` | Build a production bundle into `dist/`. |
| `npm run preview` | Serve the existing `dist/` build on port 8000. |
| `npm run preview:build` | Build, then preview, on port 8000. |
| `npm run deploy` | Build and publish `dist/` to GitHub Pages (`gh-pages` branch). |
| `npm run analyze` | Build with bundle-size analysis enabled. |
| `npm run lint` | Lint with Biome **and** type-check with TypeScript. |
| `npm run biome` | Auto-fix formatting and lint issues with Biome. |
| `npm run biome:lint` | Run Biome lint only (no formatting). |
| `npm test` | Run the test suite once (Vitest). |
| `npm run test:coverage` | Run tests with a coverage report. |
| `npm run test:watch` | Run tests in watch mode. |
| `npm run test:ui` | Open the Vitest UI. |
| `npm run tsc` | Type-check without emitting output. |
| `npm run openapi` | Generate API service code from `config/oneapi.json`. |
| `npm run i18n-remove` | Strip i18n wrappers, inlining `zh-CN` strings. |
| `npm run record` | Record request data for the login scene (for mocks). |
| `npm run simple` | Strip demo pages and unused deps down to a minimal template (irreversible). |

> [!NOTE]
> Code quality is enforced by **Biome** (a single fast tool replacing ESLint + Prettier) and **Vitest** for tests. Do not add ESLint or Prettier plugins — they will conflict with Biome.

---

## 15. Troubleshooting

Issues are formatted as: the error, its cause, the fix, and how to prevent it. Several are drawn from real questions in the project's issue tracker.

### Error: `Can't resolve 'tailwindcss'`

```text
Module not found: Error: Can't resolve 'tailwindcss'
```

- **Cause:** A dependency-resolution hiccup during install, most often on Windows 11 (issues [#11747](https://github.com/ant-design/ant-design-pro/issues/11747), [#11818](https://github.com/ant-design/ant-design-pro/issues/11818)).
- **Solution:** Remove the install artifacts and reinstall cleanly:

  ```bash
  rm -rf node_modules package-lock.json
  npm install
  ```

- **Prevention:** Use the required Node version (`>= 22`) and a clean checkout. Avoid mixing package managers (don't run `pnpm install` then `npm install` in the same project).

### Error: `The project won't start` / dev server exits immediately

- **Cause:** A stale UmiJS temp directory or a Node version mismatch (issue [#11864](https://github.com/ant-design/ant-design-pro/issues/11864)).
- **Solution:** Delete the generated temp directory and restart:

  ```bash
  rm -rf src/.umi
  npm start
  ```

- **Prevention:** Don't commit `src/.umi` (it's auto-generated). Keep Node up to date.

### Error: `POST http://localhost:8000/api/login/account 404 (Not Found)`

- **Cause:** You're running without mock and without a configured proxy/backend, so `/api/*` has nowhere to go (issue [#11799](https://github.com/ant-design/ant-design-pro/issues/11799)).
- **Solution:** Either run with mocks (`npm start`) or configure a real target in `config/proxy.ts` and run `npm run dev`.
- **Prevention:** Use `npm start` while developing UI; only switch to `start:no-mock`/`dev` once your backend or proxy is ready.

### Login appears to succeed but nothing is protected / no token is sent

- **Cause:** This is by design in the demo. The request interceptor that would attach an auth token is **commented out** in `src/requestErrorConfig.ts`, and the mock backend grants admin to everyone (issues [#11550](https://github.com/ant-design/ant-design-pro/issues/11550), [#11869](https://github.com/ant-design/ant-design-pro/issues/11869)).
- **Solution:** Implement real auth — uncomment and complete the request interceptor to attach your token, and replace the mock login with your backend. See the [Admin Guide](/guides/ant-design/ant-design-pro/admin-guide/) security section.
- **Prevention:** Treat the bundled auth as a UI demo, not a security boundary.

### Preview site won't log in / `workers.dev` is unreachable

```text
Failed to fetch https://pro-api.ant-design-demo.workers.dev/api/login/account
```

- **Cause:** The public demo backend (a Cloudflare Worker) is blocked or unreachable from your network (issue [#11868](https://github.com/ant-design/ant-design-pro/issues/11868)).
- **Solution:** Run locally with mocks (`npm start`) instead of relying on the hosted demo, or stand up your own backend.
- **Prevention:** For local development, prefer mock mode — it has no external dependencies.

### The dark mask / overlay sticks around after paging or opening the sidebar

- **Cause:** A known interaction bug between pagination and the sidebar overlay in some layouts (issues [#11597](https://github.com/ant-design/ant-design-pro/issues/11597), [#11821](https://github.com/ant-design/ant-design-pro/issues/11821)).
- **Solution:** Update to the latest template (fixes are tracked for v6.1.0). As a workaround, switch the layout mode (e.g. `mix` → `side`) in the Setting Drawer.
- **Prevention:** Track the latest release; this class of UI bug is fixed upstream over time.

### Language switcher won't hide even when disabled

- **Cause:** A bug where `layout.locale` couldn't disable the language switcher in non-`mix` layouts (issues [#11820](https://github.com/ant-design/ant-design-pro/issues/11820), [#11845](https://github.com/ant-design/ant-design-pro/issues/11845)).
- **Solution:** Update to the latest template, where the switcher correctly respects the `locale: false` setting in all layouts.
- **Prevention:** Keep your template current; v6.1.0 addresses it.

---

## 16. FAQ

**Q: Is Ant Design Pro a library I install with npm?**
No. It is a **boilerplate project** you clone and build on. There is no published `ant-design-pro` package to depend on — the repository *is* the starting point for your application.

**Q: Do I have to use all these demo pages?**
No. They're reference examples. Delete the ones you don't need, or run `npm run simple` to strip them all at once.

**Q: How do I disable mock data?**
Run `npm run start:no-mock` (or `cross-env MOCK=none max dev`). Configure your real backend target in `config/proxy.ts` first.

**Q: How do I change the primary/brand color?**
Edit `colorPrimary` in `config/defaultSettings.ts`. Use the Setting Drawer in dev mode to preview colors live before committing the value.

**Q: How do I switch to dark mode by default?**
Set `navTheme: 'realDark'` in `config/defaultSettings.ts`, or toggle it live in the Setting Drawer.

**Q: How do I add a new page?**
Create the component in `src/pages/`, register its route in `config/routes.ts`, and add the menu translation in `src/locales/*/menu.ts`. See [Add a new page](#7-everyday-development-tasks).

**Q: How do I add global shared state?**
Create a file in `src/models/` that exports a custom Hook, then read it anywhere with `useModel('<filename>')`. This is UmiJS Max's lightweight data-flow model.

**Q: What's the difference between `useRequest`, React Query, and `getInitialState`?**
`getInitialState` (in `src/app.tsx`) fetches global startup data once (like the current user). `useRequest` is UmiJS Max's simple data-fetching hook. **React Query** (`@tanstack/react-query`) is the project's standard for cached server state with mutations — prefer it for list/detail screens. The demo CRUD table uses React Query.

**Q: How do I generate API service code instead of writing it by hand?**
Define your API contract in `config/oneapi.json` (OpenAPI format), then run `npm run openapi`. It generates typed request functions into `src/services/ant-design-pro/`. **Don't hand-edit the generated files** — change the schema and regenerate.

**Q: Which languages are supported out of the box?**
Eight: Simplified & Traditional Chinese, English, Japanese, Portuguese (Brazil), Indonesian, Persian, and Bengali. The default is Simplified Chinese — change it in `config/config.ts`.

**Q: How do I upgrade my project to a newer Ant Design Pro version later?**
The project ships an AI-assisted upgrade skill. Install it with `npx skills add ant-design/ant-design-pro`, then run `/pro-upgrade` in Claude Code. It diffs the latest template against your project and helps merge framework changes while preserving your business code.

**Q: How do I deploy to a sub-path instead of the domain root?**
Set `publicPath` in `config/config.ts` to your sub-path (e.g. `'/admin/'`) before building, so asset URLs resolve correctly.

**Q: Does the dev proxy work in production?**
No. Proxies are a dev-server feature only. In production, point your app at an absolute API `baseURL` or serve `/api/*` from the same origin behind your own reverse proxy.

---

_Generated June 2026 from ant-design/ant-design-pro at 7f89ecb. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._