https://github.com/docspring/craco-less
A Less plugin for craco / react-scripts / create-react-app
https://github.com/docspring/craco-less
Last synced: about 1 year ago
JSON representation
A Less plugin for craco / react-scripts / create-react-app
- Host: GitHub
- URL: https://github.com/docspring/craco-less
- Owner: DocSpring
- License: mit
- Created: 2018-11-12T18:31:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-05-02T11:49:43.000Z (about 2 years ago)
- Last Synced: 2025-03-28T10:07:17.921Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 3.1 MB
- Stars: 123
- Watchers: 6
- Forks: 46
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/DocSpring/craco-less/actions/workflows/test.yml)
[](https://coveralls.io/github/DocSpring/craco-less?branch=master)
[](LICENSE)
---
### 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](#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](https://github.com/dilanx/craco) plugin that adds Less support to [create-react-app](https://facebook.github.io/create-react-app/) version >= 2.
> Use [react-app-rewired](https://github.com/timarney/react-app-rewired) for `create-react-app` version 1.
## Ant Design
If you want to use [Ant Design](https://ant.design/) with `create-react-app`,
you should use the [`craco-antd`](https://github.com/DocSpring/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`: `^5.0.1`
- `@craco/craco`: `^7.1.0`
## Installation
First, follow the [`craco` Installation Instructions](https://github.com/gsoft-inc/craco/blob/master/packages/craco/README.md#installation) to install the `craco` package, create a `craco.config.js` file, and modify the scripts in your `package.json`.
Then install `craco-less`:
```bash
$ yarn add -D craco-less
# OR
$ npm i -D craco-less
```
## Usage
Here is a complete `craco.config.js` configuration file that adds Less compilation to `create-react-app`:
```js
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](https://webpack.js.org/loaders/style-loader/#options)
- `options.cssLoaderOptions`
- _Default:_ `{ importLoaders: 2 }`
- [View the `css-loader` options](https://webpack.js.org/loaders/css-loader/#options)
- `options.postcssLoaderOptions`
- _Default:_ `{ ident: "postcss", plugins: () => [ ... ] }`
- [View the `postcss-loader` options](https://webpack.js.org/loaders/postcss-loader/#options)
- `options.lessLoaderOptions`
- _Default:_ `{}`
- [View the `less-loader` documentation](https://webpack.js.org/loaders/less-loader/)
- [View the Less options](http://lesscss.org/usage/#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](https://github.com/webpack-contrib/mini-css-extract-plugin)
- `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`:
```js
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`
```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](https://webpack.js.org/loaders/css-loader/), [less-loader](https://webpack.js.org/loaders/less-loader/) ...) for _less modules_.
For example:
```js
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](https://github.com/css-modules/css-modules) regarding relative file paths in `url(...)` statements. [See this issue for an explanation.](https://github.com/webpack-contrib/less-loader/issues/109#issuecomment-253797335)
> ([Copied from the less-loader README](https://github.com/webpack-contrib/less-loader#css-modules-gotcha).)
## 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](https://github.com/dilanx/craco/blob/master/packages/craco/README.md#configuration-overview). You can use `CracoLessPlugin` while making other changes to `babel` and `webpack`, etc.
## Contributing
Install dependencies:
```bash
$ 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](https://prettier.io/)
- `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`
## License
[MIT](./LICENSE)
## Contributors
- [ndbroadbent](https://github.com/ndbroadbent)
- [tux-tn](https://github.com/tux-tn)
- [alexandrtovmach](https://github.com/alexandrtovmach)
- [cemremengu](https://github.com/cemremengu)
- [AO17](https://github.com/AO17)
- [Vovan-VE](https://github.com/Vovan-VE)
- [yifanwangsh](https://github.com/yifanwangsh)
- [swillis12](https://github.com/swillis12)
- [nutgaard](https://github.com/nutgaard)
- [alexander-svendsen](https://github.com/alexander-svendsen)
- [sgtsquiggs](https://github.com/sgtsquiggs)
- [fanck0605](https://github.com/fanck0605)
- [xyy94813](https://github.com/xyy94813)
- [kamronbatman](https://github.com/kamronbatman)
- [fourpastmidnight](https://github.com/fourpastmidnight)