From dcb11174468af53132d7d95e4c36d0493a91dd2f Mon Sep 17 00:00:00 2001 From: harhao Date: Mon, 15 Jun 2026 12:47:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=EF=BC=8C?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E8=8B=B1=E6=96=87=E7=89=88=20README=5FEN.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 191 +++++++++++++++++-------------- README_EN.md | 316 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 421 insertions(+), 86 deletions(-) create mode 100644 README_EN.md diff --git a/README.md b/README.md index b1dbd0a..89ef3ee 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ -

-

BundleKit

- 前端多构建器工具集——一套配置，驱动多种构建工具 + 统一前端构建，告别配置迁移。

@@ -11,35 +9,40 @@ npm version license docs + English

--- ## 简介 -BundleKit 是一个**前端多构建器统一工具集**，目标是让开发者通过**一份 `.bundlekitrc.ts` 配置文件**，即可自由切换底层构建工具，无需关心各构建器之间配置的差异。 +BundleKit 是一个**前端多构建器统一工具集**。通过**一份 `.bundlekitrc.ts` 配置文件**，即可自由切换底层构建工具，无需关心各构建器之间配置的差异。 + +不再被单一构建工具绑定，迁移工具时无需重写构建配置。BundleKit 通过适配器模式抹平了各构建器的差异，让你专注于业务开发。 -目前已支持的构建器包括：Webpack、Vite、Rollup、Rspack、Rolldown、Parcel、esbuild。 +--- ## 特性 -- 🚀 **多构建器支持**：一套配置，支持切换 Webpack / Vite / Rollup / Rspack / Rolldown / Parcel / esbuild -- 🧩 **插件化架构**：通过插件扩展框架支持（React / Vue 3 / Svelte / Angular / Node.js） -- 🎯 **CLI 脚手架**：一行命令创建项目，交互式选择框架、构建器、语言 -- 🔌 **插件管理**：为已有项目添加框架插件（`bundlekit-cli add`） -- 📦 **库模式**：支持 ESM / CJS / UMD 多格式输出（`--lib` / `--library-name`） -- 🖥️ **SSR 支持**：内置服务端渲染支持，双通道构建（`--ssr`） -- 🤖 **MCP 集成**：提供 MCP Server，支持通过 AI 工具链创建和管理项目 -- 📖 **文档站点**：基于 dumi 的完整文档和贡献指南 -- ✅ **完善的测试**：单元测试 + 集成测试 + E2E 测试 +- 🚀 **多构建器支持** — 一套配置，支持切换 Webpack / Vite / Rollup / Rspack / Rolldown / Parcel / esbuild +- 🧩 **插件化架构** — 通过插件扩展框架支持：React / Vue 3 / Svelte / Angular / Node.js +- 🎯 **CLI 脚手架** — 交互式创建项目，选择框架、构建器、语言和包管理器 +- 🔌 **插件管理** — 为已有项目添加框架插件（`bc add react`） +- 📦 **库模式** — 支持 ESM / CJS / UMD 多格式输出（`--lib` / `--library-name`） +- 🖥️ **SSR 支持** — 内置服务端渲染，双通道构建（`--ssr`） +- 🤖 **MCP 集成** — 通过 Model Context Protocol 支持 AI 驱动的项目创建 +- 📖 **文档站点** — 完整文档 + AI 智能问答助手 +- ✅ **完善的测试** — 单元测试 + 集成测试 + E2E 测试（Vitest + Playwright） + +--- ## 快速开始 ### 创建新项目 ```bash -# 使用完整命令 -bundlekit-cli create my-app +# 完整命令 +npx @bundlekit/cli create my-app # 或使用短别名 bc create my-app @@ -82,9 +85,11 @@ bc create my-lib --template node-ts --bundler rollup --lib --library-name MyLib **包管理器**：`npm` `yarn` `pnpm`（默认 pnpm） +--- + ## 配置说明 -项目根目录创建 `.bundlekitrc.ts`（或 `.bundlekitrc.js`）文件： +在项目根目录创建 `.bundlekitrc.ts`（或 `.bundlekitrc.js`）配置文件： ```typescript import { defineConfig } from '@bundlekit/service'; @@ -114,7 +119,9 @@ export default defineConfig({ }); ``` -## 使用构建服务 +> **切换构建器**只需修改 `bundler` 字段值，其余配置无需变动。 + +### 使用构建服务 ```bash # 启动开发服务器 @@ -124,23 +131,57 @@ ds serve ds build ``` +--- + +## 架构 + +BundleKit 采用**适配器模式**，将你的配置与具体构建器解耦： + +``` + .bundlekitrc.ts 统一配置 + │ + ▼ + Service (核心) 编排插件和构建器解析 + │ + ▼ + 构建器适配器 将统一配置转换为构建器原生格式 + ┌─────┴─────┐ + │ Vite │ Webpack │ Rollup │ Rspack │ Rolldown │ Parcel │ esbuild + └─────┬─────┘ + │ + ▼ + 框架插件 设置框架上下文 + ┌─────┴─────┐ + │ React │ Vue 3 │ Svelte │ Angular │ Node.js + └───────────┘ +``` + +每个构建器适配器实现 `IBuildToolAdapter` 接口，包含三个核心方法： + +- `transformConfig(config)` — 将统一配置转换为构建器原生格式 +- `validateConfig(config)` — 构建前校验配置 +- `run(config)` — 执行构建 + +--- + ## MCP Server -BundleKit 提供了 MCP（Model Context Protocol）Server，可以通过 AI 工具链来创建和管理项目： +BundleKit 提供了 **Model Context Protocol (MCP) Server**，支持通过 AI 工具链来创建和管理项目： ```bash -# 启动 MCP Server -bundlekit-cli-mcp +npx @bundlekit/cli-mcp ``` -MCP Server 提供以下工具： +| 工具 | 说明 | +|------|------| +| `create-project` | 创建新项目 | +| `add-plugin` | 添加框架插件 | +| `list-templates` | 列出可用模板 | +| `help` | 获取帮助信息 | -- `create-project` — 创建新项目 -- `add-plugin` — 添加框架插件 -- `list-templates` — 列出可用模板 -- `help` — 获取帮助信息 +可与任何支持 MCP 协议的 AI 助手集成，实现自然语言驱动的项目脚手架。 -适用于与支持 MCP 协议的 AI 助手集成，实现自然语言驱动的项目脚手架。 +--- ## 项目结构 @@ -148,30 +189,16 @@ MCP Server 提供以下工具： bundlekit/ ├── packages/ │ ├── bundlekit-cli/ # CLI 脚手架工具 (@bundlekit/cli) -│ ├── bundlekit-service/ # 构建服务 (@bundlekit/service) +│ ├── bundlekit-service/ # 核心构建服务 (@bundlekit/service) │ ├── bundlekit-shared-utils/ # 共享工具库 (@bundlekit/shared-utils) │ ├── bundlekit-cli-mcp/ # MCP Server (@bundlekit/cli-mcp) -│ ├── bundlekit-bundler-webpack/ # Webpack 适配器 -│ ├── bundlekit-bundler-vite/ # Vite 适配器 -│ ├── bundlekit-bundler-rollup/ # Rollup 适配器 -│ ├── bundlekit-bundler-rspack/ # Rspack 适配器 -│ ├── bundlekit-bundler-rolldown/ # Rolldown 适配器 -│ ├── bundlekit-bundler-parcel/ # Parcel 适配器 -│ ├── bundlekit-bundler-esbuild/ # esbuild 适配器 -│ ├── bundlekit-plugin-react/ # React 框架插件 -│ ├── bundlekit-plugin-vue/ # Vue 3 框架插件 -│ ├── bundlekit-plugin-svelte/ # Svelte 框架插件 -│ ├── bundlekit-plugin-angular/ # Angular 框架插件 -│ ├── bundlekit-plugin-node/ # Node.js 插件 -│ ├── bundlekit-plugin-mock/ # Mock API 插件 -│ ├── bundlekit-request/ # HTTP 请求工具 (@bundlekit/request) +│ ├── bundlekit-bundler-*/ # 构建器适配器（7 个） +│ ├── bundlekit-plugin-*/ # 框架插件（6 个） +│ ├── bundlekit-request/ # HTTP 请求工具 │ ├── bundlekit-docs/ # 文档站点 (dumi) -│ └── bundlekit-docs-agent/ # 文档查询 Agent -├── __tests__/ # 测试目录 -│ ├── unit/ # 单元测试 -│ └── integration/ # 集成测试 & E2E 测试 -├── scripts/ # 构建验证脚本 -├── openspec/ # AI Spec 配置 +│ └── bundlekit-docs-agent/ # 基于 RAG 的文档问答 Agent +├── __tests__/ # 测试目录（单元 + 集成 + E2E） +├── scripts/ # 构建与验证脚本 └── turbo.json # Turborepo 任务编排 ``` @@ -183,8 +210,8 @@ bundlekit/ | `bundlekit-service` | `@bundlekit/service` | 核心构建服务 | | `bundlekit-shared-utils` | `@bundlekit/shared-utils` | 共享工具库 | | `bundlekit-cli-mcp` | `@bundlekit/cli-mcp` | MCP Server | -| `bundlekit-bundler-webpack` | `@bundlekit/bundler-webpack` | Webpack 适配器 | | `bundlekit-bundler-vite` | `@bundlekit/bundler-vite` | Vite 适配器 | +| `bundlekit-bundler-webpack` | `@bundlekit/bundler-webpack` | Webpack 适配器 | | `bundlekit-bundler-rollup` | `@bundlekit/bundler-rollup` | Rollup 适配器 | | `bundlekit-bundler-rspack` | `@bundlekit/bundler-rspack` | Rspack 适配器 | | `bundlekit-bundler-rolldown` | `@bundlekit/bundler-rolldown` | Rolldown 适配器 | @@ -194,10 +221,12 @@ bundlekit/ | `bundlekit-plugin-vue` | `@bundlekit/plugin-vue` | Vue 3 框架插件 | | `bundlekit-plugin-svelte` | `@bundlekit/plugin-svelte` | Svelte 框架插件 | | `bundlekit-plugin-angular` | `@bundlekit/plugin-angular` | Angular 框架插件 | -| `bundlekit-plugin-node` | `@bundlekit/plugin-node` | Node.js / TypeScript 插件 | +| `bundlekit-plugin-node` | `@bundlekit/plugin-node` | Node.js 插件 | | `bundlekit-plugin-mock` | `@bundlekit/plugin-mock` | Mock API 插件 | | `bundlekit-request` | `@bundlekit/request` | HTTP 请求工具 | +--- + ## 开发 ### 环境要求 @@ -219,45 +248,35 @@ pnpm build:all # 单独构建 pnpm build:shared # 先构建共享工具 -pnpm build:webpack # 构建 webpack 适配器 -pnpm build:vite # 构建 vite 适配器 -pnpm build:rollup # 构建 rollup 适配器 -pnpm build:rspack # 构建 rspack 适配器 -pnpm build:parcel # 构建 parcel 适配器 -pnpm build:esbuild # 构建 esbuild 适配器 -pnpm build:service # 构建服务（依赖适配器） -pnpm build:docs # 构建文档站点 +pnpm build:vite # Vite 适配器 +pnpm build:webpack # Webpack 适配器 +# ... 其他适配器 +pnpm build:service # 核心服务（依赖适配器） +pnpm build:docs # 文档站点 ``` ### 测试 ```bash -# 单元测试 -pnpm test - -# 集成测试 -pnpm test:integration - -# E2E 测试 -pnpm test:e2e - -# 全部测试 -pnpm test:all +pnpm test # 单元测试 +pnpm test:integration # 集成测试 +pnpm test:e2e # E2E 测试 +pnpm test:all # 全部测试 ``` ### 构建验证 ```bash -# 验证包产物 -pnpm verify:pack - -# 验证模板完整性 -node scripts/validate-templates.mjs +pnpm verify:pack # 验证包产物 +node scripts/validate-templates.mjs # 验证模板完整性 ``` +--- + ## 文档 -文档站点源码位于 `packages/bundlekit-docs/`，基于 [dumi](https://d.umijs.org/) 构建。 +- **在线文档**：[bundlekit.harhao.workers.dev](https://bundlekit.harhao.workers.dev) +- **AI 文档助手**：[llm-chat-app.harhao.workers.dev](https://llm-chat-app.harhao.workers.dev) — 基于 RAG 的智能文档问答 ```bash # 本地启动文档站点 @@ -265,13 +284,7 @@ cd packages/bundlekit-docs pnpm dev ``` -在线文档：[bundlekit.harhao.workers.dev](https://bundlekit.harhao.workers.dev) - -💬 **AI 文档助手**：[llm-chat-app.harhao.workers.dev](https://llm-chat-app.harhao.workers.dev) — 基于 RAG 的智能文档问答，支持自然语言查询 BundleKit 用法和配置 - -## 贡献指南 - -贡献文档位于 `packages/bundlekit-docs/docs/contributing/`，包含： +### 贡献指南 - [贡献总览](packages/bundlekit-docs/docs/contributing/index.md) - [环境搭建](packages/bundlekit-docs/docs/contributing/setup.md) @@ -280,18 +293,24 @@ pnpm dev - [新增构建器](packages/bundlekit-docs/docs/contributing/adding-bundler.md) - [新增插件](packages/bundlekit-docs/docs/contributing/adding-plugin.md) +--- + ## CI/CD -项目使用 GitHub Actions 自动化： +通过 GitHub Actions 自动化： -- **publish-npm**：推送 `master` 分支时自动构建、测试、发布 npm 包（Changesets） -- **create-release-pr**：自动创建版本发布 PR -- **deploy-docs**：自动部署文档站点 +- **publish-npm** — 推送 `master` 分支时自动构建、测试、发布 npm 包（Changesets） +- **create-release-pr** — 自动创建版本发布 PR +- **deploy-docs** — 自动部署文档站点 + +--- ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=Harhao/bundlekit&type=Date)](https://star-history.com/#Harhao/bundlekit&Date) +--- + ## 许可证 [MIT](./LICENSE) © [harhao](https://github.com/Harhao) diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..22eebee --- /dev/null +++ b/README_EN.md @@ -0,0 +1,316 @@ +

BundleKit

+ +

+ Unified frontend builds. No more config migration. +

+ +

+ npm version + npm version + license + docs + 中文 +

+ +--- + +## Introduction + +**BundleKit** is a unified frontend build toolkit that lets you write **one `.bundlekitrc.ts` configuration** and freely switch between bundlers — Webpack, Vite, Rollup, Rspack, Rolldown, Parcel, or esbuild — without changing a single line of config. + +No more vendor lock-in. No more rewriting build configs when migrating tools. BundleKit abstracts away the differences between bundlers behind a clean adapter pattern, so you can focus on shipping features. + +--- + +## Features + +- 🚀 **Multi-bundler Support** — One config works with Webpack / Vite / Rollup / Rspack / Rolldown / Parcel / esbuild +- 🧩 **Plugin Architecture** — Extend framework support via plugins: React / Vue 3 / Svelte / Angular / Node.js +- 🎯 **CLI Scaffolding** — Interactive project creation with framework, bundler, language, and package manager selection +- 🔌 **Plugin Management** — Add framework plugins to existing projects (`bc add react`) +- 📦 **Library Mode** — Multi-format output — ESM / CJS / UMD (`--lib` / `--library-name`) +- 🖥️ **SSR Support** — Built-in server-side rendering with dual-pass build (`--ssr`) +- 🤖 **MCP Integration** — AI-powered project creation via Model Context Protocol +- 📖 **Documentation** — Full docs site with AI-powered Q&A assistant +- ✅ **Tested** — Unit tests + Integration tests + E2E tests (Vitest + Playwright) + +--- + +## Quick Start + +### Create a new project + +```bash +# Using full command +npx @bundlekit/cli create my-app + +# Or use the short alias +bc create my-app +``` + +The interactive wizard lets you choose: + +- Template (framework + language) +- Bundler +- Package manager +- SSR toggle +- Library mode toggle + +### Add plugins to existing projects + +```bash +bc add react +bc add vue +bc add svelte +bc add angular +bc add node +``` + +### Common options + +```bash +# Skip interactive prompts +bc create my-app --template react-ts --bundler vite + +# Create SSR project +bc create my-app --template vue3-ts --bundler vite --ssr + +# Create library +bc create my-lib --template node-ts --bundler rollup --lib --library-name MyLib +``` + +**Available templates**: `react-ts` `react-js` `vue3-ts` `vue3-js` `svelte-ts` `svelte-js` `angular-ts` `angular-js` `node-ts` + +**Available bundlers**: `vite` `webpack` `rspack` `rollup` `rolldown` `parcel` `esbuild` + +**Package managers**: `npm` `yarn` `pnpm` (default: pnpm) + +--- + +## Configuration + +Create a `.bundlekitrc.ts` (or `.bundlekitrc.js`) in your project root: + +```typescript +import { defineConfig } from '@bundlekit/service'; + +export default defineConfig({ + bundler: 'vite', + plugins: ['react'], + // SSR config (optional) + ssr: { + enabled: true, + }, + // Dev environment + dev: { + port: 3000, + proxy: { + '/api': { + target: 'http://localhost:8080', + changeOrigin: true, + }, + }, + }, + // Production build + build: { + outDir: 'dist', + sourcemap: true, + }, +}); +``` + +> **Switching bundlers** only requires changing `bundler: 'vite'` to `bundler: 'webpack'` — everything else stays the same. + +### Use the build service + +```bash +# Start dev server +ds serve + +# Production build +ds build +``` + +--- + +## Architecture + +BundleKit follows the **Adapter Pattern** to decouple your config from any specific bundler: + +``` + .bundlekitrc.ts Unified config + │ + ▼ + Service (core) Orchestrates plugins & bundler resolution + │ + ▼ + Bundler Adapter Translates config → native bundler format + ┌─────┴─────┐ + │ Vite │ Webpack │ Rollup │ Rspack │ Rolldown │ Parcel │ esbuild + └─────┬─────┘ + │ + ▼ + Framework Plugin Sets framework context + ┌─────┴─────┐ + │ React │ Vue 3 │ Svelte │ Angular │ Node.js + └───────────┘ +``` + +Each bundler adapter implements the `IBuildToolAdapter` interface with three core methods: + +- `transformConfig(config)` — Convert unified config to bundler-native format +- `validateConfig(config)` — Validate config before build +- `run(config)` — Execute the build + +--- + +## MCP Server + +BundleKit provides a **Model Context Protocol (MCP) Server** for AI-driven project scaffolding: + +```bash +npx @bundlekit/cli-mcp +``` + +| Tool | Description | +|------|-------------| +| `create-project` | Create a new project | +| `add-plugin` | Add a framework plugin | +| `list-templates` | List available templates | +| `help` | Get CLI help | + +Integrate with any MCP-compatible AI assistant to scaffold projects via natural language. + +--- + +## Project Structure + +``` +bundlekit/ +├── packages/ +│ ├── bundlekit-cli/ # CLI scaffolding (@bundlekit/cli) +│ ├── bundlekit-service/ # Core build service (@bundlekit/service) +│ ├── bundlekit-shared-utils/ # Shared utilities (@bundlekit/shared-utils) +│ ├── bundlekit-cli-mcp/ # MCP Server (@bundlekit/cli-mcp) +│ ├── bundlekit-bundler-*/ # Bundler adapters (7 adapters) +│ ├── bundlekit-plugin-*/ # Framework plugins (6 plugins) +│ ├── bundlekit-request/ # HTTP request utility +│ ├── bundlekit-docs/ # Documentation site (dumi) +│ └── bundlekit-docs-agent/ # RAG-based docs Q&A agent +├── __tests__/ # Tests (unit + integration + E2E) +├── scripts/ # Build & validation scripts +└── turbo.json # Turborepo orchestration +``` + +## Packages + +| Package | npm | Description | +|---------|-----|-------------| +| `bundlekit-cli` | `@bundlekit/cli` | CLI scaffolding tool | +| `bundlekit-service` | `@bundlekit/service` | Core build service | +| `bundlekit-shared-utils` | `@bundlekit/shared-utils` | Shared utilities | +| `bundlekit-cli-mcp` | `@bundlekit/cli-mcp` | MCP Server | +| `bundlekit-bundler-vite` | `@bundlekit/bundler-vite` | Vite adapter | +| `bundlekit-bundler-webpack` | `@bundlekit/bundler-webpack` | Webpack adapter | +| `bundlekit-bundler-rollup` | `@bundlekit/bundler-rollup` | Rollup adapter | +| `bundlekit-bundler-rspack` | `@bundlekit/bundler-rspack` | Rspack adapter | +| `bundlekit-bundler-rolldown` | `@bundlekit/bundler-rolldown` | Rolldown adapter | +| `bundlekit-bundler-parcel` | `@bundlekit/bundler-parcel` | Parcel adapter | +| `bundlekit-bundler-esbuild` | `@bundlekit/bundler-esbuild` | esbuild adapter | +| `bundlekit-plugin-react` | `@bundlekit/plugin-react` | React plugin | +| `bundlekit-plugin-vue` | `@bundlekit/plugin-vue` | Vue 3 plugin | +| `bundlekit-plugin-svelte` | `@bundlekit/plugin-svelte` | Svelte plugin | +| `bundlekit-plugin-angular` | `@bundlekit/plugin-angular` | Angular plugin | +| `bundlekit-plugin-node` | `@bundlekit/plugin-node` | Node.js plugin | +| `bundlekit-plugin-mock` | `@bundlekit/plugin-mock` | Mock API plugin | +| `bundlekit-request` | `@bundlekit/request` | HTTP request utility | + +--- + +## Development + +### Prerequisites + +- Node.js >= 20 +- pnpm >= 8.15.9 + +### Install + +```bash +pnpm install +``` + +### Build + +```bash +# Build all packages +pnpm build:all + +# Build individually +pnpm build:shared # Shared utilities first +pnpm build:vite # Vite adapter +pnpm build:webpack # Webpack adapter +# ... other adapters +pnpm build:service # Core service (depends on adapters) +pnpm build:docs # Documentation site +``` + +### Test + +```bash +pnpm test # Unit tests +pnpm test:integration # Integration tests +pnpm test:e2e # E2E tests +pnpm test:all # All tests +``` + +### Verify + +```bash +pnpm verify:pack # Verify package artifacts +node scripts/validate-templates.mjs # Validate templates +``` + +--- + +## Documentation + +- **Online docs**: [bundlekit.harhao.workers.dev](https://bundlekit.harhao.workers.dev) +- **AI docs assistant**: [llm-chat-app.harhao.workers.dev](https://llm-chat-app.harhao.workers.dev) — RAG-based Q&A for BundleKit usage and configuration + +```bash +# Run docs locally +cd packages/bundlekit-docs +pnpm dev +``` + +### Contributing + +- [Contributing Overview](packages/bundlekit-docs/docs/contributing/index.md) +- [Setup](packages/bundlekit-docs/docs/contributing/setup.md) +- [Testing](packages/bundlekit-docs/docs/contributing/testing.md) +- [Release](packages/bundlekit-docs/docs/contributing/release.md) +- [Adding a Bundler](packages/bundlekit-docs/docs/contributing/adding-bundler.md) +- [Adding a Plugin](packages/bundlekit-docs/docs/contributing/adding-plugin.md) + +--- + +## CI/CD + +Automated via GitHub Actions: + +- **publish-npm** — Auto build, test & publish to npm on `master` push (Changesets) +- **create-release-pr** — Auto-create version release PRs +- **deploy-docs** — Auto-deploy documentation site + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=Harhao/bundlekit&type=Date)](https://star-history.com/#Harhao/bundlekit&Date) + +--- + +## License + +[MIT](./LICENSE) © [harhao](https://github.com/Harhao)