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
2. Requirements
3. Installation
4. Running the Project
5. Logging In (Demo Credentials)
6. The Template Pages
7. Everyday Development Tasks
8. Customizing the Layout & Theme
9. Internationalization
10. The AI Assistant Page
11. Building & Deploying
12. Simple Mode: Stripping to a Minimal Template
13. How It Works (Concepts)
14. Command Reference
15. Troubleshooting
16. FAQ

1. Quick Start

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

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.

$ 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.

Warning

On Windows 11, an early v6 setup could fail with Can't resolve 'tailwindcss' (reported in issues #11747 and #11818). If you hit it, delete node_modules and package-lock.json, then reinstall. See Troubleshooting.

To check your versions:

node --version
npm --version

v22.11.0
10.9.0

3. Installation

Step 1 — Get the code

Clone (recommended)

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, extract it, and cd into the folder.

Step 2 — Install dependencies

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).

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:

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).

npm start

  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), 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:

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 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

Form

List

Profile

Result

Exception

Account

AI Assistant

/chatbot — A complete chat interface built with Ant Design X. Streaming responses, conversation history, a "thinking" panel, and Markdown rendering. See The AI Assistant Page.

User (no layout)

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:

   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:

   {
     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):

   '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 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/:

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:

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:

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.

// 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.

// 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',
};

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:

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.

Users switch language from the globe icon in the header. The default locale is zh-CN; set your own default in config/config.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

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 — 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:

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

npm run build

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

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

Preview the build locally

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.

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

GitHub Pages (built-in)

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.

# 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.

Built on UmiJS Max

Ant Design Pro is a UmiJS Max 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.

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'

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

• Cause: A dependency-resolution hiccup during install, most often on Windows 11 (issues #11747, #11818).

• Solution: Remove the install artifacts and reinstall cleanly:

  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).

• Solution: Delete the generated temp directory and restart:

  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).
• 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, #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 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

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).
• 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, #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, #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.

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.