craco-antd v2.0.0
Community Maintained
We rely on your help to keep this project up to date and work with the latest versions of craco
and react-scripts
.
Before you send a PR, please check the following:
- 100% test coverage
jest --coverage --testPathIgnorePatterns test-app
- Code is formatted with Prettier
yarn prettier --write "**/*.{js,jsx,json,css,scss,html,md,yml}"
- No ESLint warnings
yarn eslint --fix --ext .js lib/
- No security vulnerabilities in any NPM packages
yarn audit
You are also welcome to add your GitHub username to the Contributors section at the bottom of this README. (optional)
Please don't send a pull request if it does not meet the above requirements
Pull requests will be ignored and closed if there is a failing build on Travis CI.
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- An easy way to customize the theme. Set your custom variables in
./antd.customize.less
Supported Versions
The latest version of craco-antd
is tested with:
react-scripts
:^5.0.0
@craco/craco
:^6.4.3
craco-less
:^2.0.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
and antd
:
$ yarn add craco-antd antd
# OR
$ npm i -S craco-antd antd
craco-antd
only has a "peer dependency" forantd >= 3.0.0
. You should addantd
to your ownpackage.json
and use a fixed version (e.g.3.11.2
). Be careful when upgradingantd
, because unexpected changes could break your application.
Basic 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 }],
};
Advanced Usage
Here is a production-ready craco.config.js
file that sets up webpackbar
and webpack-bundle-analyzer
.
It also sets up Preact with the craco-preact
plugin. (Preact is faster and smaller than React, and it works fine with Ant Design.)
I put my custom theme variables in src/style/AntDesign/customTheme.less
. I also use that folder for some custom components and other CSS.
const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer");
const WebpackBar = require("webpackbar");
const CracoAntDesignPlugin = require("craco-antd");
const path = require("path");
// Don't open the browser during development
process.env.BROWSER = "none";
module.exports = {
webpack: {
plugins: [
new WebpackBar({ profile: true }),
...(process.env.NODE_ENV === "development"
? [new BundleAnalyzerPlugin({ openAnalyzer: false })]
: []),
],
},
plugins: [
{ plugin: require("craco-preact") },
{
plugin: CracoAntDesignPlugin,
options: {
customizeThemeLessPath: path.join(
__dirname,
"src/style/AntDesign/customTheme.less"
),
},
},
],
};
See the Reload Custom Variables During Development section to wrap your "start" script with
nodemon
.
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;
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 themodifyVars
option inless-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.
Reload Custom Variables During Development
The webpack dev server needs to be restarted whenever you make a change to your custom theme variables. (It's not possible to reload this file automatically, because the variables are set in the webpack config. I tried to fix this issue but hit a dead-end.)
However, you can automatically restart webpack by wrapping craco start
with nodemon
.
Install nodemon
:
yarn add -D nodemon
# Or globally (not recommended):
npm install -g nodemon
Update the "start" script in package.json
:
"scripts": {
"start": "nodemon -w ./antd.customize.less --exec \"craco start\"",
}
(Change
./antd.customize.less
if you are using a different file.)
The webpack dev server will now be restarted whenever you make a change to ./antd.customize.less
.
Restart Webpack When craco.config.js
Changes
While you're here, you can also add -w craco.config.js
to restart webpack whenever your craco
configuration changes (craco
doesn't do this automatically):
"scripts": {
"start": "nodemon -w craco.config.js -w ./antd.customize.less --exec \"craco start\"",
}
Disable "Open In Browser"
By default, create-react-app
will open a new browser tab every time it starts. This can be really annoying, especially if you set up the nodemon
watcher. You can disable this behavior with an environment variable: BROWSER=none
.
You can set this in an .env
file:
BROWSER=none
I prefer to set it at the top of craco.config.js
:
// Don't open the browser during development
process.env.BROWSER = "none";
Options
You can pass an options
object to configure the loaders and plugins. You can also pass a modifyLessRule
callback to have full control over the Less webpack rule.
See the craco-less
documentation for more information about these options:
options.styleLoaderOptions
options.cssLoaderOptions
options.postcssLoaderOptions
options.lessLoaderOptions
options.miniCssExtractPluginOptions
options.modifyLessRule
See the babel-plugin-import
documentation for more information about this option:
options.babelPluginImportOptions
Example:
module.exports = {
plugins: [
{
plugin: CracoAntDesignPlugin,
options: {
lessLoaderOptions: {
modifyVars: { "@primary-color": "#1DA57A" },
strictMath: true,
noIeCompat: true,
},
cssLoaderOptions: {
modules: true,
localIdentName: "[local]_[hash:base64:5]",
},
babelPluginImportOptions: {
libraryDirectory: "es",
},
},
},
],
};
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
- Run
- 100% test coverage
- Coverage will be printed after running tests.
- Check the coverage results in your browser:
open coverage/lcov-report/index.html
- No ESLint errors
yarn lint
- All code is formatted with Prettier
yarn format
- If you use VS Code, you should enable the
formatOnSave
option.
Test Application
We've included a test React application in this repo, under ./test-app
.
Install dependencies:
cd test-app
yarn install
Test the app in development:
yarn start
Test the production build:
yarn build
# Install the "serve" package
yarn global add serve
# Serve the production build
serve -s build
Releasing a new version
- Make sure the "Supported Versions" section is updated at the top of the README.
- Check which files will be included in the NPM package:
npm pack
- Update
.npmignore
to exclude any files.
- Release new version to NPM:
npm publish
License
Contributors
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago