Ant Design Pro

Ant Design Pro integrates @tanstack/react-query via the @umijs/max reactQuery plugin (configured in config/config.ts using reactQuery: {}).

Currently, the project follows the latest stable version of v5. Do not attempt to migrate to v6 until it is officially released and the Umi reactQuery plugin has been updated to support it.

The @utoo/pack bundler is a transitive dependency of @umijs/max (via umi and @umijs/preset-umi).

Do not upgrade @utoo/pack independently in Ant Design Pro. Upgrading it manually can cause version mismatches with the @umijs/max bundler and will be overwritten during the next @umijs/max update. The correct way to upgrade the bundler is to upgrade @umijs/max itself, allowing the Umi team to manage compatibility.

Permissions are defined in src/access.ts based on the initialState. You can apply permissions in two ways:

1. Route-level: Add the access key to your route configuration in config/routes.ts.
2. Component-level: Use the <Access> component for declarative control or the useAccess hook for imperative logic.

// File: src/access.ts
export default function access(initialState: { currentUser?: API.CurrentUser }) {
  const { currentUser } = initialState;
  return {
    canAdmin: currentUser?.access === 'admin',
    canUser: !!currentUser,
  };
}

// Component-level usage
import { Access, useAccess } from '@umijs/max';

// Declarative
<Access accessible={access.canAdmin}>
  <AdminPanel />
</Access>

// Imperative
const access = useAccess();
if (access.canAdmin) { /* ... */ }

To strip away demo pages and unused dependencies to create a minimal project, use the npm run simple command.

Warning: Always commit your current changes before running this command so you can revert if necessary.

git add -A && git commit -m "chore: save before simple"
npm run simple
npm install

As of the v6.1.0 evaluation, Node.js 20 has reached End of Life (EOL). It is recommended to upgrade the minimum required Node.js version to 22 (Active LTS) to ensure security and ecosystem compatibility (e.g., with vitest and @biomejs/biome).

To perform this upgrade, update the following:

1. Set engines.node to ">=22.0.0" in package.json.
2. Update CI workflow matrices (e.g., node-version or node_version) to use version 22.
3. Update any project documentation (like CLAUDE.md) that references Node.js version requirements.

// package.json
{
  "engines": {
    "node": ">=22.0.0"
  }
}

Ant Design Pro uses a model-based approach for global state via Umi's useModel hook.

1. Create a model: Create a file in src/models/ (e.g., src/models/myModel.ts). The filename becomes the model key.
2. Export a Hook: The file must export a custom Hook as the default export.
3. Consume the state: Use useModel('filename') in any component to access the exported data.

// src/models/myModel.ts
export default function useMyModel() {
  return { data: 'some state' };
}

// In a component
import { useModel } from '@umijs/max';
const { data } = useModel('myModel');

If you are using Claude Code, you can leverage built-in skills to manage your project.

/pro-upgrade — Project Upgrade Assistant

Automatically upgrades your project to the latest Ant Design Pro version by diffing the latest template against your current code. It handles dependencies, config changes, and code pattern migrations.

/antd — Ant Design CLI Helper

Provides access to @ant-design/cli for querying component information and debugging.

• npx antd info <Component>: View props, types, and version info.
• npx antd demo <Component> <demo>: Get working code examples.
• npx antd lint ./src: Check for deprecated or problematic usage.
• npx antd doc <Component>: Access full component documentation.

To install or update these skills in your project, run: npx skills add ant-design/ant-design-pro

The npm run simple command converts your project into a 'Simple Version' by deleting demo pages and unused dependencies.

WARNING: This operation is irreversible.

You must commit all current changes before running this command.

git add -A && git commit -m "chore: save before simple"
npm run simple
npm install

After performing dependency upgrades, follow this checklist to ensure project stability:

1. Linting: Run npm run lint (verifying both Biome and tsc).
2. Antd Linting: Run npx antd lint ./src to check for Ant Design component usage issues.
3. Build: Run npm run build to ensure the production build succeeds.
4. Testing: Execute all tests to ensure no regressions were introduced.
5. Development: Run npm start to verify the development server works.
6. Visual Inspection: Perform a visual spot-check of critical pages: Login, Dashboard, Table-list, and Forms.

npm run lint
npx antd lint ./src
npm run build
npm test
npm start

Ant Design Pro can automatically generate API service code from an OpenAPI specification.

Workflow:

1. Configure your OpenAPI settings in config/oneapi.json.
2. Run npm run openapi to generate the code.
3. The generated code will be placed under src/services/.

CRITICAL: Never edit the generated code in src/services/ant-design-pro/ manually. If changes are needed, modify config/oneapi.json and regenerate the code.