@vureact/compiler-core 1.7.0 → 1.8.1

package/README.en.md

@@ -1,34 +1,55 @@
 # @vureact/compiler-core
 
-**Write Vue, Ship Production-Ready React** — Build React 18+ apps with the Vue 3 mental model.
+**Write in Vue, generate maintainable React.**
+
+`@vureact/compiler-core` is the **CLI and core compiler package** of VuReact.  
+It compiles Vue 3 SFC, script, and style files into **pure React 18+ code**, making it suitable for progressive migration and for teams that want to keep Vue authoring conventions while targeting a React app.
+
+It is a **compile-time solution**, not a runtime bridge.
 
-[![Npm](https://img.shields.io/npm/v/@vureact/compiler-core.svg?label=Npm&style=flat-square)](https://vureact.top/en/)
 [![Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
-[![Monthly](https://img.shields.io/npm/dm/@vureact/compiler-core?label=Monthly&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://opensource.org/licenses/MIT)
-[![Vue 3](https://img.shields.io/badge/Vue-3.x-42b883)](https://vuejs.org/)
-[![React 18+](https://img.shields.io/badge/React-18%2B-61dafb)](https://reactjs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/vureact-js/core/blob/master/LICENSE)
 
 English | [简体中文](./README.md)
 
-## Introduction
+## Who this package is for
 
-`@vureact/compiler-core` is the core compilation package of VuReact, responsible for compiling Vue 3 SFC, script files, and style files into React 18+ JSX/TSX code ready for production.
+- Teams progressively migrating a Vue 3 codebase to React
+- Developers who want Vue-style authoring with React output
+- Projects that need a config-driven `build/watch` compilation workflow
 
-## Installation
+## Usage
+
+### 1. Install
 
 ```bash
 npm install -D @vureact/compiler-core
 ```
 
-## Quick Start
+You can also use:
 
-👉 **Full tutorial: [VuReact Website - Quick Start](https://vureact.top/en/guide/quick-start.html)**
+```bash
+pnpm add -D @vureact/compiler-core
+yarn add -D @vureact/compiler-core
+```
 
-### Configuration Example
+### 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({
+  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';
@@ -44,25 +65,128 @@ export default defineConfig({
 });
 ```
 
-### Commands
+If your project uses Vue Router, you will usually also add:
+
+```ts
+router: {
+  configFile: 'src/router/index.ts',
+}
+```
+
+### 3. Start with a single-file pilot
+
+If you want to validate the transformation first, start with one SFC:
+
+```ts
+export default defineConfig({
+  input: './src/your-component.vue',
+  exclude: ['src/main.ts'],
+});
+```
+
+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. Expand to the whole project
+
+Once the single-file pilot works, point `input` to a directory:
+
+```ts
+export default defineConfig({
+  input: './src',
+  exclude: ['src/main.ts'],
+});
+```
+
+This will recursively process Vue, script, and style files under that directory.
+
+> 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. Run the compiler
+
+```bash
+# one-time build
+npx vureact build
+
+# watch mode
+npx vureact watch
+```
+
+If you prefer scripts, add them to `package.json`:
+
+```json
+{
+  "scripts": {
+    "vr:build": "vureact build",
+    "vr:watch": "vureact watch"
+  }
+}
+```
+
+### 6. Check the output
+
+By default, VuReact generates:
+
+- `.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/
+├── .vureact/
+│   ├── cache/
+│   ├── react-app/
+│   │   ├── src/
+│   │   ├── package.json
+│   │   ├── vite.config.ts
+├── src/
+├── package.json
+└── vureact.config.ts
+```
+
+You can then run the generated app directly:
 
 ```bash
-npx vureact build      # Build project
-npx vureact watch      # Watch mode
+cd .vureact/react-app
+npm install
+npm run dev
 ```
 
-## Ecosystem
+If you want a deeper explanation of the two modes, continue with:
+
+- [Watch Mode](https://vureact.top/en/guide/watch-mode.html)
+- [Incremental Compilation](https://vureact.top/en/guide/incremental-compilation.html)
 
-- **[VuReact Runtime Core](https://runtime.vureact.top/en)**: React-compatible implementations of Vue core APIs
-- **[VuReact Router](https://router.vureact.top/en)**: Vue Router 4.x → React Router DOM 7.9+ conversion
+## What this package is not
 
-If necessary, you can choose [☣️ Mixed Coding](https://vureact.top/en/guide/mind-control-readme.html) to directly use the React ecosystem.
+- 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
 
-## FAQ
+## Related packages
 
-👉 [FAQ](https://vureact.top/en/guide/faq.html)
+- [@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
 
-## 🔗 Links
+## Documentation
+
+- [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>
-- Documentation: <https://vureact.top/en>
+- Docs: <https://vureact.top/en>
+
+MIT License © 2025 Ruihong Zhong (Ryan John)

package/README.md

@@ -1,34 +1,54 @@
 # @vureact/compiler-core
 
-**写 Vue，交付生产级 React 代码** —— 让你在 Vue 3 心智下，编译出 React 18+ 应用的编译工具。
+**写 Vue，生成可维护的 React。**
+
+`@vureact/compiler-core` 是 VuReact 的 **CLI 与核心编译包**。  
+它用于将 Vue 3 的 SFC、脚本和样式文件编译为 **纯 React 18+ 代码**，适合渐进式迁移，以及“保持 Vue 心智模型、输出 React 工程”的场景。
+
+它是 **编译时方案**，不是运行时桥接。
 
-[![Npm](https://img.shields.io/npm/v/@vureact/compiler-core.svg?label=Npm&style=flat-square)](https://vureact.top/)
 [![Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
-[![Monthly](https://img.shields.io/npm/dm/@vureact/compiler-core?label=Monthly&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://opensource.org/licenses/MIT)
-[![Vue 3](https://img.shields.io/badge/Vue-3.x-42b883)](https://vuejs.org/)
-[![React 18+](https://img.shields.io/badge/React-18%2B-61dafb)](https://reactjs.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)
 
-## 简介
+## 这个包适合谁
 
-`@vureact/compiler-core` 是 VuReact 的核心编译包，负责将 Vue 3 单文件组件、脚本文件和样式文件**三位一体**编译为可直接用于生产环境的 React 18+ JSX/TSX 代码。
+- 正在把 Vue 3 项目渐进迁移到 React
+- 想继续按 Vue 约定写代码，但产出 React 工程
+- 需要基于配置文件执行 `build/watch` 编译流程
 
-## 安装
+## 使用方式
+
+### 1. 安装
 
 ```bash
 npm install -D @vureact/compiler-core
 ```
 
-## 快速开始
+也可以使用：
 
-👉 **完整教程请访问：[VuReact - 快速开始](https://vureact.top/guide/quick-start.html)**
+```bash
+pnpm add -D @vureact/compiler-core
+yarn add -D @vureact/compiler-core
+```
 
-### 配置示例
+### 2. 创建配置文件
 
-`vureact.config.ts`
+在项目根目录新建 `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';
@@ -44,26 +64,128 @@ export default defineConfig({
 });
 ```
 
-### 编译命令
+如果项目使用 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
-npx vureact build      # 编译项目
-npx vureact watch      # 监听模式
+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 常用内置组件、核心 Composition API 等
-- **[VuReact Router](https://router.vureact.top/)**：支持 Vue Router 4.x → React Router DOM 7.9+ 转换
+- [@vureact/runtime-core](https://runtime.vureact.top/)：React 版 Vue 运行时适配 API
+- [@vureact/router](https://router.vureact.top/)：Vue Router 到 React Router 的适配方案
 
-如果确实需要，你可以选择 [☣️混合编写](https://vureact.top/guide/mind-control-readme.html)，以此直接使用 React 生态。
+## 文档入口
 
-## 常见问题
+- [快速开始](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)
 
-👉 请查阅[官网 FAQ 章节](https://vureact.top/guide/faq.html)
+## 仓库与许可证
 
-## 🔗 链接
+- GitHub: <https://github.com/vureact-js/core>
+- 文档: <https://vureact.top>
 
-- GitHub：<https://github.com/vureact-js/core>
-- Gitee：<https://gitee.com/vureact-js/core>
-- 文档：<https://vureact.top>
+MIT License © 2025 Ruihong Zhong (Ryan John)