Umi 提供了大量开箱即用的功能，其中我认为非常好用的功能是支持自动使用 CSS Modules。这篇文章分享下如何在 create-react-app 中也使用这个功能，并介绍这个功能的原理。
什么是自动使用 CSS Modules
用过 Umi 或 Ant Design Pro 的同学应该知道，在项目中可以通过 import 的写法区分是否使用 CSS Modules
// 使用 CSS Modules
import styles from './index.less';
// 不使用
import './index.less';
这种写法十分方便。然而这个功能并不是 css-loader 原生支持的，因为 loader 并不知道这个文件是如何被引用的。因此，在 create-react-app 中，需要通过给样式文件名增加 .module 以标识使用 CSS Modules。例如：
// 使用 CSS Modules
import styles from './index.module.less';
// 不使用
import styles from './index.less';
import './index.less';
这种方法对文件名有较强的约束，因此 Umi 对这种情况进行了优化。
如何使用
首先需要借助 craco 使 create-react-app 的 webpack 可配置。
craco的作用类似react-app-rewired，但是比它的配置更友好。craco将常用的配置提取出来作为配置项，而react-app-rewired只能通过转换函数的方式修改webpack的配置，往往还需要customize-cra配合使用。
安装 craco 和插件 craco-css-modules
$ npm install @craco/craco craco-css-modules -D
创建 build 文件夹，并创建 craco.config.js 文件，内容为：
const CracoCSSModules = require('craco-css-modules');
module.exports = {
plugins: [
{ plugin: CracoCSSModules },
]
};
修改 package.json 中 npm scripts
"scripts": {
- "start": "react-scripts start",
+ "start": "craco start",
- "build": "react-scripts build",
+ "build": "craco build"
}
package.json 中新增 cracoConfig 字段，并指向配置文件
"cracoConfig": "./build/craco.config.js"
这里也可以选择使用 craco 支持的约定方式，在项目根目录下创建 craco.config.js 或 .cracorc.js。个人不太喜欢在根目录有很多文件。
大功告成，即可不再需要写 .module.css 这种特殊命名了。
在以下版本进行过验证：
- react-scripts:
^5.0.0- @craco/craco:
^6.4.0- craco-css-modules：
^1.0.1
Less 支持
create-react-app 本身不支持 less，可以通过 craco-less 支持。
安装插件 craco-less
$ npm install craco-less -D
在 craco.config.js 使用插件：
const CracoLess = require('craco-less');
const CracoCSSModules = require('craco-css-modules');
module.exports = {
plugins: [
{ plugin: CracoLess },
{ plugin: CracoCSSModules },
],
};
即可使用 less 语法
在以下版本进行过验证：
- craco-less：
^2.0.0
原理
通过打印 Webpack 配置可以看到，create-react-app 针对 css 文件生成了以下解析配置（less、sass 类似）：
modules: {
rules: [
{
test: /\.css$/,
use: [
{
loader: 'css-loader',
modules: false,
},
],
},
{
test: /\.module\.css$/,
use: [
{
loader: 'css-loader',
modules: {
localIdentName: '',
},
},
],
},
],
}
因此，create-react-app 通过判断文件名中的 .module 来区分 css-loader 是否开启 modules。那如何不通过文件名呢？我们可以借助 resourceQuery，给需要开启的文件增加 query 参数来区分。
modules: {
rules: [
{
test: /\.css$/,
oneOf: [
{
resourceQuery: /modules/,
use: [
{
loader: 'css-loader',
modules: {
localIdentName: '',
},
},
],
},
{
use: [
{
loader: 'css-loader',
modules: false,
},
],
},
],
},
],
}
如何让这些 less 文件有这个 query 呢？我们可以借助 babel 来实现，通过修改 AST（抽象语法树）将 import ... from 语法中引用的 less 文件拼接上 ?modules query。
const CSS_EXT_NAMES = ['.css', '.less', '.sass', '.scss'];
function transform() {
return {
visitor: {
ImportDeclaration(path, { opts }) {
const {
specifiers,
source,
source: { value },
} = path.node;
if (specifiers.length && CSS_EXT_NAMES.includes(extname(value))) {
source.value = `${value}?${opts.flag || 'modules'}`;
}
},
},
};
}
以上实现来自于
@umijs/babel-plugin-auto-css-modules，craco-css-modules为了支持esbuild没有选择使用babel，而是通过 Webpack 插件AutoCSSModulesWebpackPlugin实现。原理是一致的。
通过以上转换后，使用了 CSS Modules 的 less 文件结尾会多出 query，从而被 Webpack 使用开启 modules 的 css-loader 处理。
总结一下原理，关键点在于：
- 配置 Webpack 的
modules.resolve，通过oneOf+resourceQuery对带 query 的样式文件开启 CSS Modules - 通过 Babel 给
import...from语法的less文件增加 query
craco-css-modules 也是基于以上原理实现的，通过 craco 的插件机制对 Webpack 的配置进行以上修改。源代码：https://github.com/crazyurus/craco-css-modules
示例项目
以下是一个开箱即用的项目模版，使用了 craco craco-less craco-css-modules，支持自动使用 CSS Modules。可以直接基于此模版创建项目。
以下是两个完整的项目，基于上面的模版开发，供大家参考。