让 create-react-app 支持自动使用 CSS Modules

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 处理。

总结一下原理，关键点在于：

1. 配置 Webpack 的 modules.resolve，通过 oneOf + resourceQuery 对带 query 的样式文件开启 CSS Modules
2. 通过 Babel 给 import ... from 语法的 less 文件增加 query

craco-css-modules 也是基于以上原理实现的，通过 craco 的插件机制对 Webpack 的配置进行以上修改。源代码：github.com/crazyurus/c…

示例项目

以下是一个开箱即用的项目模版，使用了 craco craco-less craco-css-modules，支持自动使用 CSS Modules。可以直接基于此模版创建项目。

• github.com/crazyurus/c…

以下是两个完整的项目，基于上面的模版开发，供大家参考。

• github.com/crazyurus/c…
• github.com/crazyurus/e…