craco-antd

Craco Ant Design Plugin

This is a craco plugin that makes it easy to use the Ant Design UI library with create-react-app version >= 2.

Use react-app-rewired for create-react-app version 1.

craco-antd includes:

• Less (provided by craco-less)
• babel-plugin-import to only import the required CSS, instead of everything
• A nicer way to customize the theme. Save your modified variables in antd.customize.json

Supported Versions

craco-antd is tested with:

• react-scripts: ^2.1.1
• @craco/craco: ^2.4.0

Installation

First, follow the beginning of the Ant Design create-react-app Documentation to set up your app with Ant Design. (Stop before the "Advanced Guides" section, because this plugin handles all of that for you.)

Then, follow the craco Installation Instructions to install the craco package, create a craco.config.js file, and modify the scripts in your package.json.

Then install craco-antd:

$ yarn add craco-antd

# OR

$ npm i -S craco-antd

Usage

Here is a complete craco.config.js configuration file that sets up Less compilation and babel-plugin-import for create-react-app:

const CracoAntDesignPlugin = require("craco-antd");

module.exports = {
  plugins: [{ plugin: CracoAntDesignPlugin }]
};

Customize Ant Design Theme

You can modify the default Ant Design theme by changing some Less variables.

craco-antd will look for variables in a Less file at ./antd.customize.less. (You can customize this file path with the customizeThemeLessPath option.)

// ./antd.customize.less
@primary-color: #1da57a;
@link-color: #1da57a;

Here's a list of all the variables that can be modified.

You can also customize these variables directly in your craco.config.js with the customizeTheme option:

const CracoAntDesignPlugin = require("craco-antd");

module.exports = {
  plugins: [
    {
      plugin: CracoAntDesignPlugin,
      options: {
        customizeTheme: {
          "@primary-color": "#1DA57A",
          "@link-color": "#1DA57A"
        }
      }
    }
  ]
};

customizeTheme is just an alias for the modifyVars option in less-loader.

If you use multiple options to customize the theme variables, they are merged together in the following order:

• The file at options.customizeThemeLessPath (default: ./antd.customize.less)
• options.customizeTheme
• options.lessLoaderOptions.modifyVars

For more information, see Ant Design's "Customize Theme" documentation.

Loader Options

You can pass some options to configure style-loader, css-loader, and less-loader:

• options.styleLoaderOptions
  • View the style-loader options
• options.cssLoaderOptions
  • View the css-loader options
• options.lessLoaderOptions
  • View the less-loader documentation
  • View the Less options
    • You must use "camelCase" instead of "dash-case", e.g. --source-map => sourceMap

Example:

module.exports = {
  plugins: [
    {
      plugin: CracoAntDesignPlugin,
      options: {
        lessLoaderOptions: {
          modifyVars: { "@primary-color": "#1DA57A" },
          strictMath: true,
          noIeCompat: true
        },
        cssLoaderOptions: {
          modules: true,
          localIdentName: "[local]_[hash:base64:5]"
        }
      }
    }
  ]
};

Large Bundle Size from Ant Design Icons

You can use the webpack-bundle-analyzer plugin to see a breakdown of all the JS and CSS in your webpack build. Here's how to add this plugin to your craco.config.js configuration file:

const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer");

module.exports = {
  webpack: {
    plugins: [new BundleAnalyzerPlugin()]
  },
  plugins: [{ plugin: require("craco-antd") }]
};

If you have imported any icons from Ant Design, you will see a very large (> 500KB) entry for @ant-design/icons/lib:

This is a problem with Ant Design v3.9.0+, and it will be fixed in the next version. See this GitHub issue for more information. This comment talks about the fix, and here is the PR.

In the meantime, you can set up an import alias and only include the required icons.

Further Configuration

If you need to configure anything else for the webpack build, take a look at the Configuration Overview section in the craco README. You can use CracoAntDesignPlugin while making other changes to babel and webpack, etc.

Contributing

Install dependencies:

$ yarn install

# OR

$ npm install

Run tests:

$ yarn test

Before submitting a pull request, please check the following:

• All tests are passing
  • Run yarn test
• 100% test coverage
  • Coverage will be printed after running tests.
  • Open the coverage results in your browser: $ open coverage/lcov-report/index.html
• All code is formatted with Prettier
  • Run prettier --write **/*.js
  • If you use VS Code, I recommend enabling the formatOnSave option.

License

MIT