使用tsup构建TypeScript项目时未自动引入CSS路径的问题

问题原因 #

tsup默认会对代码进行tree shaking，CSS文件的导入属于副作用代码，如果未明确标记会被打包工具移除；同时默认的tsup配置未开启完整的CSS处理逻辑，导致生成CSS文件后未在JS产物中自动添加引入语句。

具体解决方案 #

1. 调整tsup配置，开启CSS提取与关联 #

修改tsup.config.ts，添加css配置项，确保CSS被提取为单独文件的同时，在JS产物中自动生成引入语句：

import { defineConfig } from 'tsup';

export default defineConfig({
  format: ['cjs', 'esm'],
  entry: ['./index.ts'],
  dts: true,
  shims: true,
  skipNodeModulesBundle: true,
  clean: true,
  css: {
    extract: true, // 将CSS提取为独立文件
    sourceMap: false // 按需开启，不需要可省略
  },
  treeshake: 'preserveSideEffects' // 保留副作用代码，避免CSS导入被移除
});

2. 在package.json中标记CSS为副作用 #

添加sideEffects字段，告诉打包工具所有CSS文件包含副作用，禁止tree shaking移除：

{
  // ...其他原有配置
  "sideEffects": ["*.css"]
}

3. 确保CSS导入在依赖链中生效 #

如果上述配置后仍未生效，可直接在入口文件index.ts中添加CSS导入，确保打包工具能识别到：

// index.ts
import './src/assets/style.css';
export * from "./src/types";
export * from "./src/main";

4. 完善TypeScript的CSS类型声明 #

确保custom.d.ts中有CSS模块的类型声明，避免TS编译报错：

// custom.d.ts
declare module '*.css' {
  const styles: Record<string, string>;
  export default styles;
}

验证效果 #

重新执行npm run build，检查dist目录下的JS文件（index.js和index.mjs），应该自动包含import './index.css'语句，无需手动添加。

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