Skip to content

Commit d08b010

Browse files
committed
docs: simplify readme
1 parent f0fdcef commit d08b010

File tree

2 files changed

+21
-532
lines changed

2 files changed

+21
-532
lines changed

README-zh.md

Lines changed: 14 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -8,53 +8,14 @@
88

99
⚡️ 零配置的 ESM/TS 包构建工具。基于 [**oxc**](https://oxc.rs/)[**rolldown**](https://rolldown.rs/)[**rolldown-plugin-dts**](https://github.com/sxzz/rolldown-plugin-dts) 驱动。
1010

11-
- 👌 专注于 ESM 兼容性。
12-
- 🌱 全新重构,清理代码并移除遗留功能。
13-
- 🚀 使用 [**oxc**](https://oxc.rs/)(转换)和 [**rolldown**](https://rolldown.rs/)(打包),构建速度大幅提升!
14-
1511
## 功能特性
1612

17-
### 🚀 核心功能
18-
- **快速**: 基于 [rolldown](https://rolldown.rs/)[oxc](https://oxc.rs/) 构建
19-
- **打包**: 将库与依赖项一起打包
20-
- **转换**: 将源代码转换为不同格式
21-
- **TypeScript**: 一流的 TypeScript 支持,自动生成 `.d.ts` 文件
22-
- **多入口**: 支持多个入口点
23-
- **零配置**: 开箱即用,需要时可配置
24-
25-
### 🎨 输出格式
26-
- **多格式**: 支持 ESM、CJS、IIFE、UMD 输出格式
27-
- **平台目标**: 浏览器、Node.js 和中性平台目标
28-
- **文件加载器**: 内置支持 JSON、CSS、文本和资源文件
29-
- **高级加载器**: 可配置的自定义文件类型处理
30-
31-
### 🔧 开发体验
32-
- **监听模式**: 实时文件监听和自动重建
33-
- **Stub 模式**: 文件链接的闪电般快速开发
34-
- **调试模式**: 全面的调试和日志记录
35-
- **成功回调**: 构建成功后执行命令或函数
36-
- **Vite 配置**: 重用现有的 Vite 配置
37-
38-
### 🏢 企业级功能
39-
- **工作区支持**: 具有依赖排序的 Monorepo 多包构建
40-
- **包过滤**: 工作区包的高级过滤
41-
- **导出生成**: 自动生成 package.json exports 字段
42-
- **迁移工具**: 从 tsup、unbuild、vite 和 webpack 迁移
43-
44-
### 🔌 插件系统
45-
- **Rollup 插件**: 与 Rollup 插件生态系统完全兼容
46-
- **Vite 插件**: 部分支持 Vite 插件
47-
- **Unplugin**: 跨打包器的通用插件支持
48-
- **自定义钩子**: 丰富的构建生命周期钩子
49-
- **Glob 导入**: 支持 `import.meta.glob` 的 eager/lazy 加载
50-
51-
### 📦 高级构建选项
52-
- **CJS/ESM 互操作**: 智能的 CommonJS 到 ESM 转换
53-
- **垫片**: Node.js 全局变量和浏览器环境的兼容性垫片
54-
- **跳过 Node Modules**: 可选的外部依赖处理
55-
- **Unbundle 模式**: 保持文件结构而不打包
56-
- **环境变量**: 编译时变量注入和替换
57-
- 📦 **外部依赖**: 增强的外部依赖配置
13+
**快速**: 基于 [rolldown](https://rolldown.rs/)[oxc](https://oxc.rs/) 构建
14+
📦 **零配置**: 开箱即用,需要时可配置
15+
🎯 **TypeScript**: 一流的 TypeScript 支持,自动生成 `.d.ts` 文件
16+
🔄 **双模式**: 打包或转换您的源代码
17+
🚀 **Stub 模式**: 文件链接的闪电般快速开发
18+
🏢 **企业级**: 工作区支持、包过滤、迁移工具
5819

5920
## 安装
6021

@@ -79,62 +40,22 @@ npx robuild ./src/runtime/:./dist/runtime
7940
npx robuild ./src/index.ts --watch
8041
```
8142

82-
## CLI 使用
83-
84-
### 基本命令
43+
## 使用方法
8544

8645
```sh
8746
# 打包你的库
8847
npx robuild ./src/index.ts
8948

90-
# 转换源文件(路径以 / 结尾时)
49+
# 转换源文件
9150
npx robuild ./src/runtime/:./dist/runtime
9251

9352
# 开发时的监听模式
9453
npx robuild ./src/index.ts --watch
9554
```
9655

97-
### 多格式输出
98-
99-
```sh
100-
# 构建多种格式
101-
npx robuild ./src/index.ts --format esm --format cjs --format iife
102-
103-
# 浏览器构建,带全局名称
104-
npx robuild ./src/index.ts --format iife --platform browser --global-name MyLib
105-
```
106-
107-
### 高级选项
108-
109-
```sh
110-
# 外部依赖
111-
npx robuild ./src/index.ts --external lodash --external /^@types\//
112-
113-
# 禁用清理
114-
npx robuild ./src/index.ts --no-clean
115-
116-
# 自定义工作目录
117-
npx robuild ./src/index.ts --dir ./my-project
118-
```
119-
120-
可通过 `--dir` 指定工作目录,`--watch` 启用监听模式。
121-
122-
若路径以 `/` 结尾,robuild 将使用 [oxc-transform](https://www.npmjs.com/package/oxc-transform) 进行代码转换(而非 [rolldown](https://rolldown.rs/) 打包)。
123-
124-
### API 调用
125-
126-
```js
127-
import { build } from 'robuild'
128-
129-
await build({
130-
cwd: '.',
131-
entries: ['./src/index.ts'],
132-
})
133-
```
134-
13556
## 配置
13657

137-
可在 `build.config.mjs`(或 `.ts`)中定义配置,或直接传入 `build()` 函数。
58+
在项目根目录创建 `build.config.ts`
13859

13960
```js
14061
import { defineConfig } from 'robuild'
@@ -143,100 +64,23 @@ export default defineConfig({
14364
entries: [
14465
{
14566
type: 'bundle',
146-
input: ['./src/index.ts', './src/cli.ts'],
147-
// outDir: "./dist",
148-
// minify: false,
149-
// stub: false,
150-
// rolldown: {}, // 参见 https://rolldown.rs/reference/config-options
151-
// dts: {}, // 参见 https://github.com/sxzz/rolldown-plugin-dts#options
67+
input: './src/index.ts',
68+
format: ['esm', 'cjs'],
15269
},
15370
{
15471
type: 'transform',
15572
input: './src/runtime',
15673
outDir: './dist/runtime',
157-
// minify: false,
158-
// stub: false,
159-
// oxc: {},
160-
// resolve: {}
16174
},
16275
],
163-
hooks: {
164-
// start: (ctx) => {},
165-
// end: (ctx) => {},
166-
// entries: (entries, ctx) => {},
167-
// rolldownConfig: (config, ctx) => {},
168-
// rolldownOutput: (output, res, ctx) => {},
169-
},
17076
})
17177
```
17278

173-
## 监听模式
174-
175-
在开发过程中,robuild 提供了监听模式,可在文件变化时自动重新构建项目。
176-
177-
### CLI 使用
178-
179-
```sh
180-
# 为任何构建启用监听模式
181-
npx robuild ./src/index.ts --watch
182-
183-
# 转换模式的监听
184-
npx robuild ./src/runtime/:./dist/runtime --watch
185-
186-
# 指定工作目录的监听模式
187-
npx robuild ./src/index.ts --watch --dir ./my-project
188-
```
189-
190-
### 配置
191-
192-
可在 `build.config.ts` 中配置监听行为:
193-
194-
```js
195-
import { defineConfig } from 'robuild'
196-
197-
export default defineConfig({
198-
entries: ['./src/index.ts'],
199-
watch: {
200-
enabled: true, // 默认启用监听模式
201-
include: ['src/**/*'], // 要监听的文件
202-
exclude: ['**/*.test.ts'], // 要忽略的文件
203-
delay: 100, // 重建延迟(毫秒)
204-
ignoreInitial: false, // 跳过初始构建
205-
watchNewFiles: true, // 监听新文件
206-
},
207-
})
208-
```
209-
210-
### 特性
211-
212-
- **实时重建**:源文件变化时自动重新构建
213-
- **智能文件检测**:根据构建条目自动确定要监听的文件
214-
- **防抖重建**:可配置延迟以防止过度重建
215-
- **错误恢复**:即使构建出错也会继续监听
216-
- **清晰反馈**:显示文件变化和重建状态
217-
- **优雅退出**:使用 Ctrl+C 清理退出
218-
219-
## Stub Mode
220-
221-
在本地开发时,反复执行构建或监听命令可能较为繁琐。
222-
223-
可通过 `stub: true`(条目配置)或 `--stub` CLI 参数启用存根模式。此模式下,robuild 会跳过实际构建,改为将预期输出路径链接至源文件。
224-
225-
- **打包条目**:生成 `.mjs``.d.mts` 文件直接重新导出源文件。
226-
- **转换条目**:将 src 目录符号链接至 dist 目录。
227-
228-
**注意事项:**
229-
230-
1. 需运行时原生支持 TypeScript(如 Deno、Bun、Vite 或 Node.js¹)
231-
2. **转换模式**:需配置打包工具解析 `.ts``.mjs` 扩展名。
232-
3. **打包模式**:若新增条目或修改 `default` 导出,需重新执行存根构建。
79+
## 文档
23380

234-
(1) 对于 Node.js 的解决方案:
81+
📖 **[完整文档](https://sunny-117.github.io/robuild/)**
23582

236-
- 使用 `node --experimental-strip-types`(需 Node.js [22.6](https://nodejs.org/en/blog/release/v22.6.0) 及以上)
237-
- 使用 [jiti](https://github.com/unjs/jiti)`node --import jiti/register`
238-
- 使用 [oxc-node](https://github.com/oxc-project/oxc-node)`node --import @oxc-node/core/register`
239-
- 使用 [unloader](https://github.com/sxzz/unloader)`node --import unloader/register`
83+
访问我们的文档站点获取详细指南、API 参考和示例。
24084

24185
## 相关项目
24286

0 commit comments

Comments
 (0)