Craco-less NPM

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

yarn test

Code is formatted with Prettier

yarn format

No ESLint warnings

yarn lint

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

This is a craco plugin that adds Less support to create-react-app version >= 2.

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

Ant Design

If you want to use Ant Design with create-react-app, you should use the craco-antd plugin. craco-antd includes Less and babel-plugin-import (to only include the required CSS.) It also makes it easy to customize the theme variables.

Supported Versions

craco-less is tested with:

react-scripts: ^3.2.0
@craco/craco: ^5.5.0

Installation

First, 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-less:

$ yarn add craco-less

# OR

$ npm i -S craco-less

Usage

Here is a complete craco.config.js configuration file that adds Less compilation to create-react-app:

const CracoLessPlugin = require("craco-less");

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

Configuration

You can pass an options object to configure the loaders and plugins(configure less and less modules at the same time). You can also pass a modifyLessRule(or modifyLessModuleRule) callback to have full control over the Less webpack rule.

options.styleLoaderOptions
- Default: {}
- View the style-loader options
options.cssLoaderOptions
- Default: { importLoaders: 2 }
- View the css-loader options
options.postcssLoaderOptions
- Default: { ident: "postcss", plugins: () => [ ... ] }
- View the postcss-loader options
options.lessLoaderOptions
- Default: {}
- View the less-loader documentation
- View the Less options
  - You must use "camelCase" instead of "dash-case", e.g. --source-map => sourceMap
options.miniCssExtractPluginOptions (only used in production)
- Default: {}
- View the mini-css-extract-plugin documentation
options.modifyLessRule(lessRule, context)
- A callback function that receives two arguments: the webpack rule, and the context. You must return an updated rule object.
  - lessRule:
    - test: Regex (default: /\.less$/)
    - exclude: Regex (default: /\.module\.less$/)
    - use: Array of loaders and options.
    - sideEffects: Boolean (default: true)
  - context:
    - env: "development" or "production"
    - paths: An object with paths, e.g. appBuild, appPath, ownNodeModules
options.modifyLessModuleRule(lessModuleRule, context)
- A callback function that receives two arguments: the webpack rule, and the context. You must return an updated rule object.
  - lessModuleRule:
    - test: Regex (default: /\.module\.less$/)
    - use: Array of loaders and options.
  - context:
    - env: "development" or "production"
    - paths: An object with paths, e.g. appBuild, appPath, ownNodeModules

For example, to configure less-loader:

const CracoLessPlugin = require("craco-less");

module.exports = {
  plugins: [
    {
      plugin: CracoLessPlugin,
      options: {
        lessLoaderOptions: {
          lessOptions: {
            modifyVars: {
              "@primary-color": "#1DA57A",
              "@link-color": "#1DA57A",
              "@border-radius-base": "2px",
            },
            javascriptEnabled: true,
          },
        },
      },
    },
  ],
};

CSS / Less Modules

CSS / Less modules are enabled by default, and the default file suffix for less modules is .module.less.

If your project is using typescript, please append the following code to ./src/react-app-env.d.ts

declare module "*.module.less" {
  const classes: { readonly [key: string]: string };
  export default classes;
}

You can use modifyLessModuleRule to configure the file suffix and loaders (css-loader, less-loader ...) for less modules.

For example:

const CracoLessPlugin = require("craco-less");
const { loaderByName } = require("@craco/craco");

module.exports = {
  plugins: [
    {
      plugin: CracoLessPlugin,
      options: {
        modifyLessRule(lessRule, context) {
          // You have to exclude these file suffixes first,
          // if you want to modify the less module's suffix
          lessRule.exclude = /\.m\.less$/;
          return lessRule;
        },
        modifyLessModuleRule(lessModuleRule, context) {
          // Configure the file suffix
          lessModuleRule.test = /\.m\.less$/;

          // Configure the generated local ident name.
          const cssLoader = lessModuleRule.use.find(loaderByName("css-loader"));
          cssLoader.options.modules = {
            localIdentName: "[local]_[hash:base64:5]",
          };

          return lessModuleRule;
        },
      },
    },
  ],
};

CSS modules gotcha

There is a known problem with Less and CSS modules regarding relative file paths in url(...) statements. See this issue for an explanation.

(Copied from the less-loader README.)

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 CracoLessPlugin 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.
- 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.
Using the correct webpack version as a dependency
- yarn update_deps
- NOTE: The webpack dependency is needed to silence some annoying warnings from NPM. This must always match the version from react-scripts.

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