如何构建支持CSS代码分割的UI组件库：实现样式自动按需引入

你的核心需求是：让组件库使用者仅通过导入组件（如import { Button } from '@mylib/ui'），就能自动获取对应组件的样式，且最终打包仅包含用到的组件样式，无需手动导入单个样式文件或全局样式。以下是几种成熟实现方案的评估：

方案1：组件入口文件内联导入样式 #

原理 #

在每个组件的TS/JS入口文件中，直接导入该组件对应的CSS文件。用户导入组件时，打包工具会自动分析依赖，将组件关联的样式一同打包。

示例代码 #

// @mylib/ui/src/Button/index.ts
import './button.min.css'; // 直接在组件文件中导入样式

export const Button = () => {
  // 组件渲染逻辑
  return `<button class="my-button">点击</button>`;
};

优缺点 #

• 优点：实现成本极低，用户完全无需关注样式导入；纯CSS支持所有特性（选择器、媒体查询、伪类等）；主流打包工具（Webpack、Vite、Rollup）均能自动处理依赖分析，实现按需打包。
• 缺点：依赖用户项目配置了CSS处理规则（如css-loader、postcss）；若组件样式未做命名空间隔离，可能存在样式冲突。

注意事项 #

组件库需以ESM格式输出，同时在package.json中配置sideEffects，明确告知打包工具样式文件属于有副作用的资源，避免被误删：

{
  "sideEffects": [
    "./src/**/*.css",
    "./dist/**/*.css"
  ]
}

方案2：CSS Modules + 组件自动关联 #

原理 #

每个组件使用CSS Modules编写样式，组件文件中导入对应的.module.css文件，并通过模块导出的类名渲染组件。这种方式天然隔离样式，同时实现按需加载。

示例代码 #

// @mylib/ui/src/Button/index.ts
import styles from './button.module.css';

export const Button = () => {
  return `<button class="${styles.button}">点击</button>`;
};

优缺点 #

• 优点：彻底避免样式冲突；用户导入组件时自动加载对应样式；打包工具会自动提取用到的样式。
• 缺点：样式写法需遵循CSS Modules规则，学习成本略高；组件库和用户项目均需配置支持CSS Modules。

方案3：Tree Shaking + 全局入口配置 #

原理 #

组件库将所有组件和对应样式统一暴露在全局入口文件中，利用打包工具的Tree Shaking特性，仅保留用户实际导入的组件及其关联样式。

示例代码 #

// @mylib/ui/index.ts
// 导出组件并关联样式
export { Button } from './src/Button';
import './src/Button/button.min.css';

export { Accordion } from './src/Accordion';
import './src/Accordion/accordion.min.css';

关键配置 #

需在package.json中开启Tree Shaking支持：

{
  "type": "module",
  "sideEffects": ["./**/*.css"],
  "main": "./dist/index.js",
  "module": "./dist/index.esm.js"
}

优缺点 #

• 优点：组件库结构清晰，组件与样式的关联集中管理；用户无需额外操作。
• 缺点：对打包工具的Tree Shaking能力要求较高，部分旧版工具可能无法精准识别；配置复杂度略高于方案1。

方案4：CSS-in-JS（非内联样式） #

原理 #

使用CSS-in-JS库（如Styled Components、Emotion）编写组件样式，样式代码与组件逻辑耦合，打包时仅生成用到的组件样式，并注入到页面中。

示例代码 #

// @mylib/ui/src/Button/index.ts
import styled from 'styled-components';

export const Button = styled.button`
  padding: 8px 16px;
  border-radius: 4px;
  border: none;
  cursor: pointer;

  @media (max-width: 768px) {
    padding: 6px 12px;
  }
`;

优缺点 #

• 优点：支持所有CSS特性，天然支持主题定制；自动按需加载样式，无需用户配置。
• 缺点：依赖第三方CSS-in-JS库，增加组件库体积；存在运行时开销，性能略低于纯CSS方案。

方案对比与推荐 #

优先推荐方案1：实现最简单，用户无感知，兼容性最好，完全满足你的需求。只需在每个组件文件中导入对应样式，配合正确的package.json配置即可。

内容的提问来源于stack exchange，提问作者floroz