Codakey
Play
← Back to ant-design/ant-design

How to Deploy & Use ant-design/ant-design

Ant Design Deployment & Usage Guide

1. Prerequisites

For Consumers (Using in Your Project)

  • Node.js: >= 16.0.0 (LTS recommended)
  • React: >= 16.8.0 (hooks support required)
  • TypeScript: >= 4.0.0 (optional but recommended for type safety)
  • Package Manager: npm, yarn, pnpm, or bun

For Contributors (Developing Ant Design)

  • Git: Latest stable version
  • Node.js: >= 18.0.0 (for development build tools)
  • pnpm: Preferred package manager (npm install -g pnpm)

Browser Support

  • Edge (last 2 versions)
  • Firefox (last 2 versions)
  • Chrome (last 2 versions)
  • Safari (last 2 versions)
  • Electron (last 2 versions)

2. Installation

Option A: Using in an Existing React Project

# npm
npm install antd

# yarn
yarn add antd

# pnpm
pnpm add antd

# bun
bun add antd

Optional Dependencies:

# For date handling
npm install dayjs

# For icons
npm install @ant-design/icons

Option B: Setting Up for Development/Contribution

# Clone the repository
git clone https://github.com/ant-design/ant-design.git
cd ant-design

# Install dependencies (uses pnpm by default)
pnpm install

# Or with npm
npm install

3. Configuration

Basic Usage Setup

Create or update your entry file to import styles:

// App.tsx or index.tsx
import { ConfigProvider } from 'antd';
import 'antd/dist/reset.css'; // Import CSS reset (v5+)

// Your app component
import MyApp from './MyApp';

export default () => (
  <ConfigProvider>
    <MyApp />
  </ConfigProvider>
);

Theme Customization (CSS-in-JS)

Ant Design v5+ uses CSS-in-JS. Configure themes via ConfigProvider:

import { ConfigProvider, theme } from 'antd';

const customTheme = {
  algorithm: theme.defaultAlgorithm, // or theme.darkAlgorithm
  token: {
    // Color tokens (from components/theme/interface/maps/colors.ts)
    colorPrimary: '#1890ff',
    colorText: '#333333',
    colorTextSecondary: '#666666',
    colorBorder: '#d9d9d9',
    colorBorderSecondary: '#f0f0f0',
    
    // Component-specific tokens (examples from source)
    // Menu tokens
    dropdownWidth: 120,
    zIndexPopup: 1050,
    groupTitleColor: 'rgba(0, 0, 0, 0.45)',
    itemBorderRadius: 8,
    
    // Tabs tokens
    cardBg: '#f5f5f5',
    cardHeight: 40,
    inkBarColor: '#1890ff',
  },
  components: {
    Menu: {
      itemBorderRadius: 4,
      groupTitleColor: '#999',
    },
    Tabs: {
      cardHeight: 36,
      inkBarColor: '#ff4d4f',
    },
  },
};

export default () => (
  <ConfigProvider theme={customTheme}>
    <YourApp />
  </ConfigProvider>
);

Advanced Configuration

SSR (Server-Side Rendering):

// Extract styles for SSR
import { extractStyle } from '@ant-design/cssinjs';
import { createCache } from '@ant-design/cssinjs';

const cache = createCache();

// On server
const styleText = extractStyle(cache);

Icon Configuration:

import { setTwoToneColor } from '@ant-design/icons';

setTwoToneColor('#1890ff');

4. Build & Run

For Development (Contributors)

# Start documentation site (dumi)
npm start
# or
pnpm dev

# Runs on http://localhost:8000 by default

# Build library for production
npm run build

# Run tests
npm test

# Run specific component tests
npm test -- components/button

For Consumer Applications

Standard React build commands apply:

# Development
npm run dev  # or npm start

# Production build
npm run build

# Analysis (if using create-react-app or similar)
npm run analyze

Important: Ensure your bundler supports tree-shaking for optimal bundle size:

// webpack.config.js or similar
module.exports = {
  resolve: {
    alias: {
      // Ensure single instance of react
      'react': path.resolve('./node_modules/react'),
    },
  },
  optimization: {
    usedExports: true, // Enable tree shaking
  },
};

5. Deployment

Production Optimization

1. Tree Shaking (Import on Demand)

// ✅ Good - Imports only Button and DatePicker
import { Button, DatePicker } from 'antd';

// ❌ Avoid - Imports entire library
import * as antd from 'antd';

2. CDN Usage (Global Scripts)

<!-- Development -->
<script src="https://unpkg.com/antd@5.x/dist/antd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/antd@5.x/dist/reset.css" />

<!-- Production (specific version) -->
<script src="https://unpkg.com/antd@5.12.0/dist/antd.min.js"></script>

3. Bundle Analysis

# Analyze bundle size
npm install --save-dev webpack-bundle-analyzer

# Add to package.json scripts:
# "analyze": "npm run build && npx webpack-bundle-analyzer build/static/js/*.js"

Platform-Specific Deployment

Vercel/Netlify (Static Sites):

  • Ensure antd/dist/reset.css is imported in your entry point
  • Configure build command: npm run build
  • Output directory: dist or build (depending on your setup)

Docker:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Electron:

  • Ant Design supports Electron (last 2 versions)
  • Ensure nodeIntegration is configured if using Node APIs
  • Use antd/dist/reset.css for consistent styling

6. Troubleshooting

Common Issues

Styles Not Loading

  • Symptom: Components render without styling (unstyled HTML)
  • Solution: Ensure you import antd/dist/reset.css (v5+) or antd/dist/antd.css (v4) in your entry file
  • CSS-in-JS: If using SSR, ensure extractStyle is called server-side

TypeScript Errors

  • Symptom: Cannot find module 'antd' or type errors
  • Solution: 
    // tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "node"
  }
}

Theme Not Applying

  • Symptom: Custom colors not showing
  • Solution: Check that ConfigProvider wraps your app at the root level: 
    // ❌ Wrong
<App>
  <ConfigProvider theme={theme}><Component /></ConfigProvider>
</App>

// ✅ Correct
<ConfigProvider theme={theme}>
  <App />
</ConfigProvider>

Large Bundle Size

  • Symptom: Bundle analyzer shows entire antd library
  • Solution:
    • Use babel-plugin-import (if not using v5 with tree-shaking)
    • Ensure sideEffects: false in your bundler config
    • Import specific components: import Button from 'antd/es/button'

Icon Issues

  • Symptom: Icons not displaying or causing errors
  • Solution: 
    npm install @ant-design/icons
    Check for tree-shaking issues with icons - import specifically: 
    import { HomeOutlined } from '@ant-design/icons';

SSR Hydration Mismatch

  • Symptom: Warning about text content mismatch between server/client
  • Solution: Use extractStyle from @ant-design/cssinjs on server and inject into <head>

Development Server Slow

  • Symptom: Hot reload takes too long when contributing
  • Solution: 
    # Run only specific component docs
npm start -- --filter=button

# Or use mock mode
npm run mock

Getting Help

← Project overviewView alternatives to ant-design/ant-design →