@vureact/compiler-core 1.8.3 → 1.8.5

package/README.md

@@ -1,54 +1,58 @@
 # @vureact/compiler-core
 
-**写 Vue，生成可维护的 React。**
+`@vureact/compiler-core` is a complete solution for Vue-to-React migration and hybrid development. **CLI and core compiler package** of VuReact.  
 
-`@vureact/compiler-core` 是 VuReact 的 **CLI 与核心编译包**。  
-它用于将 Vue 3 的 SFC、脚本和样式文件编译为 **纯 React 18+ 代码**，适合渐进式迁移，以及“保持 Vue 心智模型、输出 React 工程”的场景。
-
-它是 **编译时方案**，不是运行时桥接。
+It is used to fully convert Vue 3 SFCs, Scripts, and Styles into pure React (non-runtime bridge) code and output engineered artifacts, covering all core features of `<script setup>`, and supporting progressive migration and hybrid development.
 
+[![Stars](https://img.shields.io/github/stars/vureact-js/core?style=flat-square&color=magenta)](https://github.com/vureact-js/core/stargazers)
 [![Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
 [![Node](https://img.shields.io/badge/node-%3E%3D19.0.0-green?label=Node)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/vureact-js/core/blob/master/LICENSE)
 
-简体中文 | [English](./README.en.md)
+English | [简体中文](./README.zh-CN.md)
+
+## Who this package is for
 
-## 这个包适合谁
+- Projects need to migrate incrementally from Vue 3 to React, but do not want to rewrite from scratch, preferring to find existing solutions first.
+- Some developers use Vue as their primary technology stack, are accustomed to its mental model, and consider React's overhead to be heavier than Vue's.
+- Backend developers do not want to learn both frameworks; Vue is quick to pick up and intuitive, and they are reluctant to engage with React.
+- The converted React code must completely detach from the Vue runtime to avoid performance and bundle size issues caused by a dual-framework runtime.
 
-- 正在把 Vue 3 项目渐进迁移到 React
-- 想继续按 Vue 约定写代码，但产出 React 工程
-- 需要基于配置文件执行 `build/watch` 编译流程
+## Usage
 
-## 使用方式
+> 💡 **Official guide from scratch:** [VuReact Quick Start](https://vureact.top/en/guide/quick-start.html)
+>
+> 💡 **Hybrid migration walkthrough:** [Customer Support Hub (Vue + React)](https://vureact.top/en/guide/customer-support-hub)
 
-### 1. 安装
+### 1. Install
 
 ```bash
 npm install -D @vureact/compiler-core
 ```
 
-也可以使用：
+You can also use:
 
 ```bash
 pnpm add -D @vureact/compiler-core
 yarn add -D @vureact/compiler-core
 ```
 
-### 2. 创建配置文件
+### 2. Create a config file
 
-在项目根目录新建 `vureact.config.ts`：
+Create `vureact.config.ts` in your project root:
 
 ```ts
 import { defineConfig } from '@vureact/compiler-core';
 
 export default defineConfig({
-  exclude: ['src/main.ts'], // 排除 Vue 入口文件
+  input: '', // input path: a single file or a directory
+  exclude: ['src/main.ts'], // exclude the Vue entry file
 });
 ```
 
-如果你只想用默认工作区和输出目录，这样就够了。
+If you are fine with the default workspace and output directory, this is enough.
 
-如果需要显式指定输出配置，可以写成：
+If you want to make the output settings explicit, you can write:
 
 ```ts
 import { defineConfig } from '@vureact/compiler-core';
@@ -64,7 +68,7 @@ export default defineConfig({
 });
 ```
 
-如果项目使用 Vue Router，通常还会补上：
+If your project uses Vue Router, you will usually also add:
 
 ```ts
 router: {
@@ -72,9 +76,9 @@ router: {
 }
 ```
 
-### 3. 先从单文件试点
+### 3. Start with a single-file pilot
 
-如果你想先验证一个组件能否稳定转换，可以先只编译单个 SFC：
+If you want to validate the transformation first, start with one SFC:
 
 ```ts
 export default defineConfig({
@@ -83,15 +87,15 @@ export default defineConfig({
 });
 ```
 
-这适合：
+This is useful when you want to:
 
-- 先验证编译约定
-- 先看生成结果
-- 先小范围试点，而不是直接全仓推进
+- validate the compilation conventions first
+- inspect the generated output first
+- run a small pilot before scaling to the whole codebase
 
-### 4. 再扩展到整个项目
+### 4. Expand to the whole project
 
-当单文件试点通过后，再把 `input` 指向目录：
+Once the single-file pilot works, point `input` to a directory:
 
 ```ts
 export default defineConfig({
@@ -100,22 +104,22 @@ export default defineConfig({
 });
 ```
 
-这会递归处理目录下的 Vue / Script / Style 文件。
+This will recursively process Vue, script, and style files under that directory.
 
-> 注意：VuReact 优先支持基于 `<script setup>` 的现代 Vue 3 写法。  
-> 如果你的项目使用 Vue Router，请同时查看 [路由适配指南](https://vureact.top/guide/router-adaptation.html)。
+> Note: VuReact primarily targets modern Vue 3 codebases built around `<script setup>`.  
+> If your project uses Vue Router, also see the [router adaptation guide](https://vureact.top/en/guide/router-adaptation.html).
 
-### 5. 执行编译
+### 5. Run the compiler
 
 ```bash
-# 一次性编译
+# one-time build
 npx vureact build
 
-# 监听模式
+# watch mode
 npx vureact watch
 ```
 
-如果你更喜欢脚本命令，也可以写进 `package.json`：
+If you prefer scripts, add them to `package.json`:
 
 ```json
 {
@@ -126,15 +130,15 @@ npx vureact watch
 }
 ```
 
-### 6. 查看输出结果
+### 6. Check the output
 
-默认情况下，VuReact 会生成：
+By default, VuReact generates:
 
-- `.vureact/cache`：编译缓存
-- `.vureact/react-app`：React 工程产物
-- 与源目录结构对应的 `.tsx` / `.css` 文件
+- `.vureact/cache` for compilation cache
+- `.vureact/react-app` for the React app output
+- `.tsx` / `.css` files that mirror your source structure
 
-目录大致如下：
+The project layout typically looks like:
 
 ```txt
 vue-project/
@@ -149,7 +153,7 @@ vue-project/
 └── vureact.config.ts
 ```
 
-进入产物目录后可直接运行：
+You can then run the generated app directly:
 
 ```bash
 cd .vureact/react-app
@@ -157,35 +161,35 @@ npm install
 npm run dev
 ```
 
-如果你想更系统地了解 build/watch 的差异，可以继续阅读：
+If you want a deeper explanation of the two modes, continue with:
 
-- [监听模式](https://vureact.top/guide/watch-mode.html)
-- [增量编译](https://vureact.top/guide/incremental-compilation.html)
+- [Watch Mode](https://vureact.top/en/guide/watch-mode.html)
+- [Incremental Compilation](https://vureact.top/en/guide/incremental-compilation.html)
 
-## 这个包不负责什么
+## What this package is not
 
-- 它不是 Vue in React / React in Vue 的运行时桥接层
-- 它不是对任意 Vue 代码都“零约定”生效的通用 codemod
-- 它更适合遵循 VuReact 编译约定的工程化项目
+- It is not a Vue-in-React / React-in-Vue runtime bridge
+- It is not a zero-convention codemod for arbitrary Vue code
+- It works best in projects that follow VuReact compilation conventions
 
-## 相关包
+## Related packages
 
-- [@vureact/runtime-core](https://runtime.vureact.top/)：React 版 Vue 运行时适配 API
-- [@vureact/router](https://router.vureact.top/)：Vue Router 到 React Router 的适配方案
+- [@vureact/runtime-core](https://runtime.vureact.top/en/) - React-side Vue runtime adaptation APIs
+- [@vureact/router](https://router.vureact.top/en/) - Vue Router to React Router adaptation
 
-## 文档入口
+## Documentation
 
-- [快速开始](https://vureact.top/guide/quick-start.html)
-- [关键配置](https://vureact.top/guide/key-configuration.html)
-- [监听模式](https://vureact.top/guide/watch-mode.html)
-- [增量编译](https://vureact.top/guide/incremental-compilation.html)
-- [渐进式迁移指南](https://vureact.top/guide/progressive-migration.html)
-- [配置 API](https://vureact.top/api/config.html)
-- [FAQ](https://vureact.top/guide/faq.html)
+- [Quick Start](https://vureact.top/en/guide/quick-start.html)
+- [Key Configuration](https://vureact.top/en/guide/key-configuration.html)
+- [Watch Mode](https://vureact.top/en/guide/watch-mode.html)
+- [Incremental Compilation](https://vureact.top/en/guide/incremental-compilation.html)
+- [Progressive Migration Guide](https://vureact.top/en/guide/progressive-migration.html)
+- [Config API](https://vureact.top/en/api/config.html)
+- [FAQ](https://vureact.top/en/guide/faq.html)
 
-## 仓库与许可证
+## Repository and license
 
 - GitHub: <https://github.com/vureact-js/core>
-- 文档: <https://vureact.top>
+- Docs: <https://vureact.top/en>
 
 MIT License © 2025 Ruihong Zhong (Ryan John)

package/README.zh-CN.md

@@ -0,0 +1,193 @@
+# @vureact/compiler-core
+
+`@vureact/compiler-core` 是一套面向 Vue 迁移 React 和混合开发的完整解决方案。VuReact 的 **CLI 与核心编译包**。  
+它用于将 Vue 3 SFCs・Scripts・Styles 完整转为纯 React（非运行时桥接）代码并输出工程化产物，覆盖 `<script setup>` 核心全特性，支持渐进式迁移和混合开发。
+
+[![Stars](https://img.shields.io/github/stars/vureact-js/core?style=flat-square&color=magenta)](https://github.com/vureact-js/core/stargazers)
+[![Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
+[![Node](https://img.shields.io/badge/node-%3E%3D19.0.0-green?label=Node)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/vureact-js/core/blob/master/LICENSE)
+
+简体中文 | [English](./README.md)
+
+## 这个包适合谁
+
+- 项目需从 Vue 3 渐进式迁移到 React，但不想从头重写，优先寻找现有解决方案
+- 部分开发者以 Vue 为主技术栈，习惯其心智模型，认为 React 的额外负担比 Vue 更重
+- 后端开发者不想学习双框架，Vue 上手快、符合直觉，不愿接触 React
+- 转换后的 React 需完全脱离 Vue 运行时，避免双框架运行时所带来的性能和体积问题
+
+## 使用方式
+
+> 💡 **从零开始的官方指南：**[VuReact 快速入门](https://vureact.top/guide/quick-start.html)
+>
+> 💡 **混合项目迁移实践：**[客户支持协同后台（Vue + React）](https://vureact.top/guide/customer-support-hub)
+
+### 1. 安装
+
+```bash
+npm install -D @vureact/compiler-core
+```
+
+也可以使用：
+
+```bash
+pnpm add -D @vureact/compiler-core
+yarn add -D @vureact/compiler-core
+```
+
+### 2. 创建配置文件
+
+在项目根目录新建 `vureact.config.ts`：
+
+```ts
+import { defineConfig } from '@vureact/compiler-core';
+
+export default defineConfig({
+  exclude: ['src/main.ts'], // 排除 Vue 入口文件
+});
+```
+
+如果你只想用默认工作区和输出目录，这样就够了。
+
+如果需要显式指定输出配置，可以写成：
+
+```ts
+import { defineConfig } from '@vureact/compiler-core';
+
+export default defineConfig({
+  input: './src',
+  exclude: ['src/main.ts'],
+  output: {
+    workspace: '.vureact',
+    outDir: 'react-app',
+    bootstrapVite: true,
+  },
+});
+```
+
+如果项目使用 Vue Router，通常还会补上：
+
+```ts
+router: {
+  configFile: 'src/router/index.ts',
+}
+```
+
+### 3. 先从单文件试点
+
+如果你想先验证一个组件能否稳定转换，可以先只编译单个 SFC：
+
+```ts
+export default defineConfig({
+  input: './src/your-component.vue',
+  exclude: ['src/main.ts'],
+});
+```
+
+这适合：
+
+- 先验证编译约定
+- 先看生成结果
+- 先小范围试点，而不是直接全仓推进
+
+### 4. 再扩展到整个项目
+
+当单文件试点通过后，再把 `input` 指向目录：
+
+```ts
+export default defineConfig({
+  input: './src',
+  exclude: ['src/main.ts'],
+});
+```
+
+这会递归处理目录下的 Vue / Script / Style 文件。
+
+> 注意：VuReact 优先支持基于 `<script setup>` 的现代 Vue 3 写法。  
+> 如果你的项目使用 Vue Router，请同时查看 [路由适配指南](https://vureact.top/guide/router-adaptation.html)。
+
+### 5. 执行编译
+
+```bash
+# 一次性编译
+npx vureact build
+
+# 监听模式
+npx vureact watch
+```
+
+如果你更喜欢脚本命令，也可以写进 `package.json`：
+
+```json
+{
+  "scripts": {
+    "vr:build": "vureact build",
+    "vr:watch": "vureact watch"
+  }
+}
+```
+
+### 6. 查看输出结果
+
+默认情况下，VuReact 会生成：
+
+- `.vureact/cache`：编译缓存
+- `.vureact/react-app`：React 工程产物
+- 与源目录结构对应的 `.tsx` / `.css` 文件
+
+目录大致如下：
+
+```txt
+vue-project/
+├── .vureact/
+│   ├── cache/
+│   ├── react-app/
+│   │   ├── src/
+│   │   ├── package.json
+│   │   ├── vite.config.ts
+├── src/
+├── package.json
+└── vureact.config.ts
+```
+
+进入产物目录后可直接运行：
+
+```bash
+cd .vureact/react-app
+npm install
+npm run dev
+```
+
+如果你想更系统地了解 build/watch 的差异，可以继续阅读：
+
+- [监听模式](https://vureact.top/guide/watch-mode.html)
+- [增量编译](https://vureact.top/guide/incremental-compilation.html)
+
+## 这个包不负责什么
+
+- 它不是 Vue in React / React in Vue 的运行时桥接层
+- 它不是对任意 Vue 代码都“零约定”生效的通用 codemod
+- 它更适合遵循 VuReact 编译约定的工程化项目
+
+## 相关包
+
+- [@vureact/runtime-core](https://runtime.vureact.top/)：React 版 Vue 运行时适配 API
+- [@vureact/router](https://router.vureact.top/)：Vue Router 到 React Router 的适配方案
+
+## 文档入口
+
+- [快速开始](https://vureact.top/guide/quick-start.html)
+- [关键配置](https://vureact.top/guide/key-configuration.html)
+- [监听模式](https://vureact.top/guide/watch-mode.html)
+- [增量编译](https://vureact.top/guide/incremental-compilation.html)
+- [渐进式迁移指南](https://vureact.top/guide/progressive-migration.html)
+- [配置 API](https://vureact.top/api/config.html)
+- [FAQ](https://vureact.top/guide/faq.html)
+
+## 仓库与许可证
+
+- GitHub: <https://github.com/vureact-js/core>
+- 文档: <https://vureact.top>
+
+MIT License © 2025 Ruihong Zhong (Ryan John)