配置

本文档详细介绍了 LECP 构建工具的所有配置选项。

format

配置构建输出格式，支持 ESM、CJS 和 UMD 三种格式。

类型： (BundlessFormat | BundleFormat)[]

默认值： []

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	format: [{ type: "esm" }, { type: "umd" }],
});

format.type

不同格式在各模式下的支持情况：

格式	Bundless 模式	Bundle 模式
ESM	✅ (默认)	✅
CJS	✅ (默认)	✅
UMD	❌	✅ (默认)

BundlessFormat

interface BundlessFormat {
	mode?: "bundless";
	builder?: "swc";
	type: "esm" | "cjs";

	/**
	 * 入口文件夹
	 * @default "./src"
	 */
	entry?: string;

	/**
	 * 输出目录
	 * @default 根据 type 决定：
	 * - esm -> "./es"
	 * - cjs -> "./lib"
	 */
	outDir?: string;
}

BundleFormat

interface BundleFormat {
	mode?: "bundle";
	builder?: "rspack";
	type: "esm" | "cjs" | "umd";

	/**
	 * 入口文件
	 * @default "./src/index.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
	 */
	entry?: string;

	/**
	 * 输出目录
	 * @default 根据 type 决定：
	 * - esm -> "./es"
	 * - cjs -> "./lib"
	 * - umd -> "./umd"
	 */
	outDir?: string;

	/**
	 * 包名称
	 * @description UMD 模式下作为全局变量名（对应 output.library.name）
	 * - 显式传入时直接使用，不做转换
	 * - 未传入时自动从 package.json 的 name 字段生成，如 react-dom -> ReactDOM
	 */
	name?: string;

	/**
	 * 输出文件名称
	 * @default "index"
	 */
	fileName?: string;

	/**
	 * 打包排除的 package
	 * @default  esm,cjs: 排除 dependencies, peerDependencies, optionalDependencies,  umd: undefined
	 * umd 无法自动获取 root， 只能手动设置。否则可以排除 peerDependencies
	 */
	externals?: RspackConfig["externals"];

	/**
	 * 需要额外编译的 node_modules 包
	 * @default []
	 * @description 当第三方包的产物不满足当前编译目标时使用
	 * 默认不编译 node_modules 下的文件
	 * @example
	 *    ["immer"]: 编译 "immer"
	 *    [/node_modules[\\/]immer[\\/]/]: 编译 "immer"
	 *    [/[\\/]node_modules[\\/]/]: 编译 node_modules 下的所有包
	 */
	extraCompile?: (string | RegExp)[];

	/** 自定义 Rspack 配置 */
	modifyRspackConfig?: (config: RspackConfig) => RspackConfig;

	/** 通过 rspack-chain 修改配置 */
	modifyRspackChain?: (chain: RspackChain) => void;
}

targets

配置构建产物的兼容目标，影响 JavaScript 和 CSS 的编译输出。

类型： Record<string, string | number>

默认值：

仅 CJS 编译场景：{node: "20.11.0"}
其他情况：{chrome: 55}

示例：

import { defineConfig } from '@shined/lecp';

export default defineConfig({
  targets: {
    node: "22.12.0",
    // or
    chrome: 87
    // or
    es2015: "",
  },
});

:::tips 注意事项 lecp 只做语法降级，不会自动引入 polyfill。通常业务系统会自动引入 polyfill。

如果希望进一步减少体积，可以参考 externalHelpers 选项。

:::

注意事项

UMD 模式下同时设置 targets.chrome 和 targets.node 会导致构建失败，因为 output.chunkFormat 无法同时满足两个目标的要求。

解决方案：

如果确认没有代码分割，可以强制设置 output.chunkFormat
推荐做法： UMD 仅用于 Web 平台，作为 CDN 方式引入

dts

控制 TypeScript 声明文件 (.d.ts) 的生成。

类型： boolean | DtsOptions

默认值： true (等同于 { mode: "bundless", builder: "ts" })

interface DtsOptions {
	/**
	 * 生成模式
	 * - "bundle": 使用 @microsoft/api-extractor 生成单个声明文件
	 * - "bundless": 保持源文件结构，生成多个声明文件
	 * @default "bundless"
	 */
	mode: "bundless" | "bundle";

	/**
	 * 构建引擎
	 * - "ts": TypeScript 编译器（功能完整，支持 d.ts.map）
	 * - "swc": SWC 编译器（速度更快，但不支持 d.ts.map）
	 * @default "ts"
	 * @description 仅在 bundless + isolatedDeclarations 模式下可选择 swc
	 */
	builder?: "ts" | "swc";
}

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	// 关闭声明文件生成
	dts: false,

	// 或者自定义配置
	dts: {
		mode: "bundle",
		builder: "ts",
	},
});

sourcemap

类型： boolean

默认值： true

是否生成 sourcemap 文件。sourcemap 可以很好地帮助调试代码。

alias

类型： Record<string, string>

默认值： tsconfig.json 的 paths 字段获取

设置路径别名映射

支持设置相对路径，相对路径基于项目根目录。

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	alias: {
		"@": "./src",
		"@@": "./compiled",
	},
});

define

用于编译时替换全局变量和表达式。

类型： Record<string, string>

默认值： {}

参考 Rspack DefinePlugin 文档

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	define: {
		"process.env.NODE_ENV": '"production"',
		__VERSION__: '"1.0.0"',
		__DEV__: "false",
		"typeof window": '"object"',
	},
});

shims

提供跨模块系统的变量兼容性支持。

ESM 产物：可使用 CJS 变量 __dirname、__filename、require
CJS 产物：可使用 ESM 变量 import.meta.url、import.meta.dirname、import.meta.filename

类型： boolean | { legacy?: boolean }

默认值： false

shims: true：启用默认配置
shims: { legacy: true }：启用传统兼容模式

配置	Node.js 版本支持	实现方式
`legacy: false` (默认)	20.11+	使用 `import.meta.{dirname, filename}`
`legacy: true`	10.12+	使用 `fileURLToPath`,`createRequire`

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	shims: {
		legacy: true, // 支持 比 20.11更低版本的 Node.js
	},
});

externalHelpers

类型： boolean

默认值： false

SWC 编译时默认通过内联方式引入 helper 函数。开启此功能后，将从 @swc/helpers 统一引入，减少打包体积。

⚠️ 注意： 需要在 package.json 的 peerDependencies 中添加 @swc/helpers。

参考文档：SWC External Helpers

react

React 相关的编译配置。

react.runtime

类型： "classic" | "automatic" | "preserve"

默认值： "automatic"

会自动读取 tsconfig.json 中的 jsx 配置，优先级更高

JSX 转换模式：

"automatic"：使用 react/jsx-runtime（React 17+ 推荐）
"classic"：使用 React.createElement（传统方式）
"preserve"：不对 JSX 语法进行任何转换

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	react: {
		runtime: "classic",
	},
});

选择建议

推荐使用 "automatic" 模式，无需在组件中导入 React

如果需要兼容React 16.x 版本，请选择 "classic" 模式。

react.importSource

jsx 函数使用的模块名称。

tsconfig.json 中的 jsxImportSource

类型： string

如 "react", "preact", "solid-js", "@emotion/react", ...

默认值： "react"

会自动读取 tsconfig.json 中的 jsxImportSource 配置，优先级更高

示例：

import { defineConfig } from "@shined/lecp";
export default defineConfig({
	react: {
		runtime: "automatic",
		importSource: "preact",
	},
});

export default defineConfig({
	react: {
		runtime: "preserve",
		importSource: "solid-js",
	},
});

css

CSS 相关的处理配置。

css.cssModules

类型： boolean | string

默认值： false

CSS Modules 配置：

false：关闭 CSS Modules
true：使用默认命名规则 ${packageName}__[local]
string：自定义命名规则模板

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	css: {
		cssModules: true,
		// 或自定义命名规则
		// cssModules: "[name]__[local]___[hash:base64:5]"
	},
});

css.lessCompile

类型： boolean

默认值： true

在 Bundless 模式下是否编译 Less 文件为 CSS。

true：编译 .less 文件为 .css
false：直接复制 .less 文件到输出目录

css.lessOptions

类型： object

默认值： {}

额外的 Less 编译选项，详见 Less 官方文档。

css.lightningCssOptions

类型： object

默认值： {}

额外的 Lightning CSS 配置选项，详见 Lightning CSS 文档。

clean

类型： boolean

默认值： true

是否清理输出目录。

当多个 format 同时生成到一个目录时，需要关闭此选项。

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	format: [
		{ type: "umd", fileName: "index", minify: false },
		{ type: "umd", fileName: "index.min" },
	],
	clean: false,
});

exclude

类型： string[]

默认值： 自动忽略常见的测试文件和配置文件

指定编译时需要忽略的文件或目录，支持 glob 模式。

示例：

import { defineConfig } from "@shined/lecp";

export default defineConfig({
	exclude: [
		"**/*.md", // 忽略所有 markdown 文件
		"src/dev-only/**", // 忽略开发专用目录
	],
});

extends

类型： string

默认值： undefined

继承其他配置文件，类似于 tsconfig.json 的 extends 功能。适用于 monorepo 项目的配置复用场景。

路径支持：

相对路径：相对于当前配置文件
绝对路径：文件系统绝对路径
npm 包：支持从 node_modules 加载

示例：

// 子项目配置
import { defineConfig } from "@shined/lecp";

export default defineConfig({
	extends: "../shared/lecp.base.config.ts",
	// 子项目特定配置
	format: [{ type: "esm" }],
});

// 基础配置文件 (lecp.base.config.ts)
import { defineConfig } from "@shined/lecp";

export default defineConfig({
	targets: { chrome: 87 },
	dts: true,
	sourcemap: true,
});

#配置

#format

#format.type

#BundlessFormat

#BundleFormat

#targets

#dts

#sourcemap

#alias

#define

#shims

#externalHelpers

#react

#react.runtime

#react.importSource

#css

#css.cssModules

#css.lessCompile

#css.lessOptions

#css.lightningCssOptions

#clean

#exclude

#extends

配置

format

format.type

BundlessFormat

BundleFormat

targets

dts

sourcemap

alias

define

shims

externalHelpers

react

react.runtime

react.importSource

css

css.cssModules

css.lessCompile

css.lessOptions

css.lightningCssOptions

clean

exclude

extends