快速开始

安装

npm

yarn

pnpm

bun

deno

npm install @shined/lecp -D

安装完成后，你可以在项目中使用 lecp 命令或通过配置文件进行构建。

Tip

lecp 需要在 node@20.19.0+ 环境下运行, 支持 require(esm)

tsconfig.json

typescript 几乎是 npm 包的标配。自动生成 dts 文件是必不可少的。

我们需要配置面向 esm + bundler 友好的 tsconfig.json。

{
  "compilerOptions": {
    /* modules */
    "target": "ESNext",
    "module": "Preserve",
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,

    /* lint */
    "strict": true,
    "noUncheckedSideEffectImports": true,

    /* perf */
    "skipLibCheck": true,
    // "isolatedDeclarations": true,

    /* dts */
    "noEmit": true,
    "declaration": true,
    "declarationMap": true
  }
}

LECP 使用 SWC 生成 js，为了获得最佳性能和兼容性，建议使用以上配置。

tsconfig 配置说明

模块系统配置：

"module": "Preserve": 保留原始模块语法，让构建工具处理模块转换
"verbatimModuleSyntax": true: 确保类型导入/导出语法的准确性
"allowImportingTsExtensions": true: 允许导入 .ts 扩展名文件

严格模式配置：

"strict": true: 启用所有严格类型检查
"noUncheckedSideEffectImports": true: 检查副作用导入

性能优化：

"skipLibCheck": true: 跳过库文件类型检查以提升性能
"isolatedDeclarations": true: (可选) 启用独立声明模式

声明文件配置：

"noEmit": true: TypeScript 不生成文件，由 LECP 处理
"declaration": true: 生成 .d.ts 文件
"declarationMap": true: 生成声明文件映射,便于调试。

💡 注意: 这些配置遵循 SWC 迁移指南的要求，确保与 SWC 编译器的兼容性。

Node 包

对于 Node 平台包（如 SDK、工具库等），推荐以下配置

创建配置文件

在项目根目录创建 lecp.config.ts 文件：

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

export default defineConfig({
  // 输出格式：支持 ES Module 和 CommonJS
  format: [
    { type: "esm" },
    { type: "cjs" }, // 可选：目前环境是 node 20.19.0+ (require(esm)), 可以关闭
  ],

  // 目标环境
  targets: {
    node: "20.11.0",
  },

  // 生成 TypeScript 声明文件
  dts: true,

  // 启用 shims 以提供更好的兼容性
  shims: true,
});

输出结构

package.json 的 type: "module"

dist/
├── es/          # ES Module 格式
│   ├── index.js
│   ├── index.d.ts
│   ├── **/*.js
│   └── **/*.d.ts
└── lib/          # CommonJS 格式
    ├── index.cjs
    ├── index.d.cts
    ├── **/*.cjs
    └── **/*.d.cts

package.json 的 type: "commonjs"

dist/
├── es/          # ES Module 格式
│   ├── index.mjs
│   ├── index.d.mts
│   ├── **/*.mjs
│   └── **/*.d.mts
└── lib/          # CommonJS 格式
    ├── index.js
    ├── index.d.ts
    ├── **/*.js
    └── **/*.d.ts

package.json

建议在 package.json 中添加 exports 和 files 字段：

type: "module"

{
  "exports": {
    ".": {
      "import": "./es/index.js",
      "require": "./lib/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": [
    "es",
    "lib"
  ]
}

type: "commonjs"

{
  "exports": {
    ".": {
      "import": "./es/index.mjs",
      "require": "./lib/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": [
    "es",
    "lib"
  ]
}

Tip

exports 无需设置 types 值，typescript 会自动根据 import 和 require 的值推断 types的值。
没有设置 main/module/types 字段, 因为这些字段已经被 exports 字段取代, 基本无需考虑该兼容性。
需要暴露子路径，可以继续添加 exports 字段,例如:

{
  "exports": {
    "./lib/*": "./lib/*.js",
    "./lib/*.js": "./lib/*.js",
    "./lib/*.cjs": "./lib/*.cjs",
    "./es/*": "./es/*.js",
    "./es/*.js": "./es/*.js",
    "./es/*.mjs": "./es/*.mjs",
  }
}

Web 包配置

对于 Web 平台包（如 React 组件库等），推荐以下配置：

创建配置文件

在项目根目录创建 lecp.config.ts 文件：

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

export default defineConfig({
  // 输出格式：主要支持 ES Module，可选 UMD
  format: [
    { type: "esm" },
    { type: "umd" }, // 可选：用于 CDN 引用
  ],

  // 目标浏览器
  targets: {
    chrome: 55,
    safari: 12,
  },

  // 生成 TypeScript 声明文件
  dts: true,

  // 需要支持 React 16.x 版本，需要设置为 "classic"
  // react: {
  //   jsxRuntime: "classic",
  // },

  // CSS 处理
  css: {
    cssModules: true,    // 启用 CSS Modules(不推荐)
  },
});

Tip

面向浏览器的包，在今天已经无需设置 cjs 格式。

输出结构

dist/
├── es/              # ES Module 格式
│   ├── index.js
│   ├── index.d.ts
│   ├── Button/
│   │   ├── index.js
│   │   ├── index.d.ts
│   │   └── index.css
│   └── ...
└── umd/              # UMD 格式
    └── index.js

package.json

建议在 package.json 中添加 exports 和 files 字段：

{
  "exports": {
    ".": "./es/index.js",
    "./package.json": "./package.json"
  },
  "files": [
    "es",
    "umd"
  ]
}

构建

设置完 lecp.config.ts 文件后，可以使用以下命令进行构建。

常用命令

# 开发模式构建（监听文件变化）
npx lecp -w

# 生产模式构建
npx lecp

package.json

建议在 package.json 中添加以下脚本：

{
  "scripts": {
    "build": "lecp",
    "dev": "lecp -w"
  }
}

Tip

开发模式下，lecp 支持 lecp.config.ts 变动后自动重启

#快速开始

#安装

#tsconfig.json

#Node 包

#创建配置文件

#输出结构

#package.json

#Web 包配置

#创建配置文件

#输出结构

#package.json

#构建

#常用命令

#package.json

#快速开始

#安装

#tsconfig.json

#Node 包

#创建配置文件

#输出结构

#package.json

#Web 包配置

#创建配置文件

#输出结构

#package.json

#构建

#常用命令

#package.json

快速开始

安装

tsconfig.json

Node 包

创建配置文件

输出结构

package.json

Web 包配置

创建配置文件

输出结构

package.json

构建

常用命令

package.json

快速开始

安装

tsconfig.json

Node 包

创建配置文件

输出结构

package.json

Web 包配置

创建配置文件

输出结构

package.json

构建

常用命令

package.json