Libdown

更便捷地打包 TypeScript 库。 基于 Rolldown。

命令行使用

Libdown 提供了以下命令行选项：

• -r, --root <root> - 指定 package.json 所在的包根目录
• -s, --src <src> - 指定源代码的相对路径根目录（默认：src）
• -o, --out <out> - 指定常规编译的输出目录（默认：out）
• -l, --lib <lib> - 指定库入口的 glob 模式匹配字符串（默认：src/index.ts）
• -b, --bin <bin> - 指定二进制入口的 glob 模式匹配字符串（默认：src/main.ts）
• --no-command-line - 禁用命令行输出

默认行为

• 默认的二进制入口是 src/main.ts
• 默认的库入口是 src/index.ts
• 默认的输出目录是 out
• 库文件会生成三种格式：ESM（.js）、CommonJS（.cjs）和 TypeScript 声明文件（.d.ts）
• 二进制文件只生成 ESM 格式

示例

# 使用默认配置打包
libdown

# 打包到特定的输出目录
libdown -o dist

# 打包特定的二进制入口
libdown -b "src/cli.ts"

# 打包特定的库入口（支持 glob 模式）
libdown -l "src/@(entry1|entry2).ts"

# 同时指定多个选项
libdown -r . -o dist -l "src/*.ts" -b "src/cli.ts"

API 用法

Libdown 提供了多个可复用的 Rolldown 插件和工具函数，用于自定义构建流程：

libdown/aliases - 路径别名插件

一个 Rolldown 插件，用于解析 TypeScript 配置文件中的路径别名，支持多种配置方式：

import { aliases, tsconfigAliases } from "libdown/aliases"

// 方式1：使用默认的 tsconfig.json
const plugin1 = aliases()

// 方式2：指定 tsconfig.json 文件路径
const plugin2 = aliases("./tsconfig.build.json")

// 方式3：直接传入别名配置对象
const plugin3 = aliases({
  compilerOptions: {
    baseUrl: ".",
    paths: {
      "@/*": ["src/*"],
    },
  },
})

// 直接获取解析后的别名（不创建插件）
const resolvedAliases = tsconfigAliases("./tsconfig.json")

Vite 兼容插件

Libdown 还提供了 Vite 兼容的别名插件，适用于 Vite 和 Vitest 项目：

import { viteAliases } from "libdown/aliases"

// 在 Vite 配置中使用
const vitePlugin = viteAliases("./tsconfig.json")

// 在 Vitest 配置中使用
const vitestPlugin = viteAliases("./tsconfig.json")

在 Vitest Projects 嵌套时的注意事项

当在 Vitest 的 projects 配置中嵌套使用别名插件时，需要注意当前工作目录（cwd）可能与 vitest.config.ts 文件所在路径不同。为了避免路径解析错误，建议使用绝对路径：

import { viteAliases as aliases, viteExternals as externals } from "libdown"
import { join } from "node:path"
import { defineConfig } from "vitest/config"

const root = import.meta.dirname
export default defineConfig({
  plugins: [
    // 使用绝对路径确保在不同工作目录下都能正确解析
    aliases(join(root, "tsconfig.json")),
    externals(),
  ],
  test: { include: ["src/**/*.test.ts"] },
})

关键点：

• 使用 import.meta.dirname 获取配置文件所在目录
• 使用 join(root, "tsconfig.json") 构造绝对路径
• 这样可以确保无论 Vitest 在哪个工作目录下运行，都能正确找到和解析 tsconfig.json 文件

libdown/externals - 外部依赖插件

一个 Rolldown 插件，自动处理包依赖的外部化，支持灵活的包含/排除规则：

import { externals, packageExternals } from "libdown/externals"

// 创建外部依赖插件
const plugin = externals({
  root: ".", // 包根目录
  dependencies: true, // 外部化 dependencies
  devDependencies: false, // 不外部化 devDependencies
  peerDependencies: true, // 外部化 peerDependencies
  includes: [/^@internal\//], // 强制包含的模块
  excludes: [/^lodash$/], // 强制排除的模块
})

// 直接获取外部依赖函数
const externalFn = packageExternals({ dependencies: true })

libdown/options - 构建选项类型定义

提供完整的构建选项类型定义，用于自定义构建配置：

import type { BuildOptions, SpecialBuildOption } from "libdown/options"

const options: BuildOptions = {
  root: ".",
  out: "dist",
  lib: "src/index.ts",
  bin: "src/cli.ts",
  cleanOutdir: true,
  specials: {
    "special-build": {
      mode: "lib",
      input: "src/special.ts",
      outdir: "special-out",
      cleanOutdir: "force",
    } as SpecialBuildOption,
  },
}

可复用的 TypeScript 配置

Libdown 提供了一个推荐的 TypeScript 配置模板：

{
  // 通过这样即可复用配置。
  "extends": "libdown/tsconfig.json",

  // 相关路径由于基于相对路径，需要在当前库自行配置，举例如下：
  "include": ["src"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

这个配置包含了推荐的严格模式设置，适合大多数 TypeScript 库项目使用。

开源协议

本仓库采用 MulanPSL-2.0 许可证。