@vureact/compiler-core 1.6.2 → 1.7.0

package/README.en.md

@@ -1,10 +1,10 @@
 # @vureact/compiler-core
 
-A compiler that allows you to write React 18+ applications using Vue 3 syntax.
+**Write Vue, Ship Production-Ready React** — Build React 18+ apps with the Vue 3 mental model.
 
 [![Npm](https://img.shields.io/npm/v/@vureact/compiler-core.svg?label=Npm&style=flat-square)](https://vureact.top/en/)
-[![Total Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Total%20Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
-[![Monthly Downloads](https://img.shields.io/npm/dm/@vureact/compiler-core?label=Monthly%20Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
+[![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/)
@@ -12,107 +12,21 @@ A compiler that allows you to write React 18+ applications using Vue 3 syntax.
 
 English | [简体中文](./README.md)
 
-## Quick Start
-
-This section will guide you through creating, compiling, and running your first VuReact project; alternatively, you can check out the [playground](https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/master).
-
-After completion, you will clearly understand three things:
-
-1. Under what conventions input SFCs can be stably converted
-2. What the compiled directory structure looks like
-3. The semantic correspondence between the output TSX and the original SFC
-4. The compiler automatically analyzes and appends dependencies, eliminating the need to manually manage React hooks dependencies
+## Introduction
 
-## Step 0: Prepare the Directory
-
-First, set up a minimal project (illustration):
-
-```txt
-my-app/
-├─ src/
-│  ├─ components/
-│  │  └─ Counter.vue
-│  ├─ main.ts
-│  └─ index.css
-├─ package.json
-└─ vureact.config.js
-```
+`@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.
 
-## Step 1: Installation
-
-Install the VuReact compiler in your Vue project:
+## Installation
 
 ```bash
-# Using npm
 npm install -D @vureact/compiler-core
-
-# Using yarn
-yarn add -D @vureact/compiler-core
-
-# Using pnpm
-pnpm add -D @vureact/compiler-core
 ```
 
-## Step 2: Write the Input SFC
-
-`src/components/Counter.vue`
-
-```html
-<template>
-  <section class="counter-card">
-    <h2>{{ props.title || title }}</h2>
-    <p>Count: {{ count }}</p>
-    <button @click="increment">+1</button>
-    <button @click="methods.decrease">-1</button>
-  </section>
-</template>
-
-<script setup lang="ts">
-  // @vr-name: Counter (Note: Tells the compiler what component name to generate)
-  import { computed, ref } from 'vue';
-
-  // You can also use macros to define component names
-  defineOptions({ name: 'Counter' });
-
-  // Define props
-  const props = defineProps<{ title?: string }>();
-
-  // Define emits
-  const emits = defineEmits<{
-    (e: 'change'): void;
-    (e: 'update', value: number): number;
-  }>();
-
-  const step = ref(1);
-  const count = ref(0);
-  const title = computed(() => `Counter x${step.value}`);
-
-  const increment = () => {
-    count.value += step.value;
-    emits('update', count.value);
-  };
-
-  const methods = {
-    decrease() {
-      count.value -= step.value;
-    },
-  };
-</script>
-
-<style lang="less" scoped>
-  @border-color: #ddd;
-  @border-radius: 8px;
-  @padding-base: 12px;
+## Quick Start
 
-  .counter-card {
-    border: 1px solid @border-color;
-    border-radius: @border-radius;
-    padding: @padding-base;
-  }
-</style>
-```
+👉 **Full tutorial: [VuReact Website - Quick Start](https://vureact.top/en/guide/quick-start.html)**
 
-## Step 3: Configure the Compiler
+### Configuration Example
 
 `vureact.config.ts`
 
@@ -120,164 +34,35 @@ pnpm add -D @vureact/compiler-core
 import { defineConfig } from '@vureact/compiler-core';
 
 export default defineConfig({
-  input: 'src',
-  // Key: Exclude Vue entry files to avoid entry semantic conflicts
+  input: './src',
   exclude: ['src/main.ts'],
   output: {
     workspace: '.vureact',
-    outDir: 'dist',
-    // Disable environment initialization for tutorial scenarios to observe pure compilation output
-    // Recommended to enable in actual use
-    bootstrapVite: false,
+    outDir: 'react-app',
+    bootstrapVite: true,
   },
 });
 ```
 
-## Step 4: Execute Compilation
-
-### Method 1: Use the npx command
-
-Run in the root directory:
-
-```bash
-npx vureact build
-```
-
-### Method 2: Use npm scripts
-
-Add script commands to `package.json`:
-
-```json
-"scripts": {
-  "watch": "vureact watch",
-  "build": "vureact build"
-}
-```
+### Commands
 
 ```bash
-npm run build
-```
-
-## Step 5: View the Output Directory Tree
-
-Compiled directory (illustration):
-
-```txt
-my-app/
-├─ .vureact/
-│  ├─ cache/
-│  │  └─ _metadata.json
-│  └─ dist/
-│     └─ src/
-│        └─ components/
-│           ├─ Counter.tsx
-│           └─ Counter-<hash>.css
-├─ src/
-│  └─ ...
-└─ vureact.config.js
-```
-
-## Step 6: Compare the Generated Results
-
-Below is a typical formatted output (slightly simplified for illustration; the actual hash and property names are subject to local output):
-
-```tsx
-import { memo, useCallback, useMemo } from 'react';
-import { useComputed, useVRef } from '@vureact/runtime-core';
-import './Counter-a1b2c3.css';
-
-// Derived from defineProps and defineEmits
-type ICounterType = {
-  title?: string;
-  onChange: () => void;
-  onUpdate: (value: number) => number;
-};
-
-// Component wrapped with memo
-const Counter = memo((props: ICounterType) => {
-  // ref/computed converted to equivalent adaptation APIs
-  const step = useVRef(1);
-  const count = useVRef(0);
-  const title = useComputed(() => `Counter x${step.value}`);
-
-  // Automatically analyze dependencies of top-level arrow functions and append useCallback optimization
-  const increment = useCallback(() => {
-    count.value += step.value;
-    props.onUpdate?.(count.value); // emits conversion
-  }, [count.value, step.value, props.onUpdate]);
-
-  // Automatically analyze dependencies in top-level objects and append useMemo optimization
-  const methods = useMemo(
-    () => ({
-      decrease() {
-        count.value -= step.value;
-      },
-    }),
-    [count.value, step.value],
-  );
-
-  return (
-    <>
-      <section className="counter-card" data-css-a1b2c3>
-        <h2 data-css-a1b2c3>{props.title || title.value}</h2>
-        <p data-css-a1b2c3>Count: {count.value}</p>
-        <button onClick={increment} data-css-a1b2c3>
-          +1
-        </button>
-        <button onClick={methods.decrease} data-css-a1b2c3>
-          -1
-        </button>
-      </section>
-    </>
-  );
-});
-
-export default Counter;
+npx vureact build      # Build project
+npx vureact watch      # Watch mode
 ```
 
-CSS file content:
+## Ecosystem
 
-```css
-.counter-card[data-css-a1b2c3] {
-  border: 1px solid #ddd;
-  border-radius: 8px;
-  padding: 12px;
-}
-```
-
-## Key Observations
+- **[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
 
-1. The special comment `// @vr-name: Counter` defines the component name
-2. `defineProps` and `defineEmits` are converted to TS component types
-3. Non-pure UI display components are wrapped with `memo` by default
-4. `ref` / `computed` are converted to runtime adaptation APIs (`useVRef` / `useComputed`)
-5. Template event callbacks generate React-semantic `onClick`
-6. Top-level arrow functions have their dependencies automatically analyzed and `useCallback` is injected where applicable
-7. Top-level variable declarations have their dependencies automatically analyzed and `useMemo` is injected where applicable
-8. The `.value` suffix is added to original `ref` state values in JSX
-9. Less styles are compiled to CSS code
-10. Scoped styles generate hashed CSS files and add scoped attributes to elements
+If necessary, you can choose [☣️ Mixed Coding](https://vureact.top/en/guide/mind-control-readme.html) to directly use the React ecosystem.
 
 ## FAQ
 
-- Failure to exclude Vue entry files (e.g., `src/main.ts`)
-- Calling APIs that are converted to Hooks outside the top level
-- Unanalyzable expressions appearing in templates (triggering warnings)
-- Disabling style preprocessing while using `scoped`, leading to scoping failure
-
-For more details, please refer to the [FAQ](https://vureact.top/guide/en/faq.html) of the official documentation.
-
-## Ecosystem Integration
-
-- **[VuReact Runtime Core](https://runtime.vureact.top/en)**: Provides React versions of Vue's common built-in components, core Composition API, etc.
-- **[VuReact Router](https://router.vureact.top/en)**: Supports conversion from Vue Router 4.x to React Router DOM 7.9+.
-
-If necessary, you can choose [☣️ Mixed Coding](https://vureact.top/guide/mind-control-readme.html) to directly use the React ecosystem.
+👉 [FAQ](https://vureact.top/en/guide/faq.html)
 
 ## 🔗 Links
 
 - GitHub: <https://github.com/vureact-js/core>
 - Documentation: <https://vureact.top/en>
-- Playground：
-  - CRM Admin Dashboard (Standard): <https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/master>
-  - Customer Support Hub (Mixed): <https://codesandbox.io/p/github/vureact-js/example-customer-support-hub/master?import=true>

package/README.md

@@ -1,10 +1,10 @@
 # @vureact/compiler-core
 
-一个让你用 Vue 3 语法编写 React 18+ 应用的编译器。
+**写 Vue，交付生产级 React 代码** —— 让你在 Vue 3 心智下，编译出 React 18+ 应用的编译工具。
 
 [![Npm](https://img.shields.io/npm/v/@vureact/compiler-core.svg?label=Npm&style=flat-square)](https://vureact.top/)
-[![Total Downloads](https://img.shields.io/npm/dt/@vureact/compiler-core?label=Total%20Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
-[![Monthly Downloads](https://img.shields.io/npm/dm/@vureact/compiler-core?label=Monthly%20Downloads&style=flat-square)](https://www.npmjs.com/package/@vureact/compiler-core)
+[![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/)
@@ -12,107 +12,21 @@
 
 简体中文 | [English](./README.en.md)
 
-## 快速开始
-
-本节将引导你完成第一个 VuReact 项目的创建、编译和运行；或者选择查看 [CodeSandbox 在线案例](https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/master)。
-
-完成后你会明确三件事：
-
-1. 输入 SFC 在什么约定下可稳定转换
-2. 编译后目录会长什么样
-3. 输出 TSX 与原始 SFC 的语义对应关系
-4. 编译器会自动分析并追加依赖，无需手动管理 React hooks 依赖项
-
-## Step 0：准备目录
-
-先准备一个最小工程（示意）：
-
-```txt
-my-app/
-├─ src/
-│  ├─ components/
-│  │  └─ Counter.vue
-│  ├─ main.ts
-│  └─ index.css
-├─ package.json
-└─ vureact.config.js
-```
+## 简介
 
-## Step 1：安装
+`@vureact/compiler-core` 是 VuReact 的核心编译包，负责将 Vue 3 单文件组件、脚本文件和样式文件**三位一体**编译为可直接用于生产环境的 React 18+ JSX/TSX 代码。
 
-在你的 Vue 项目中安装 VuReact 编译器：
+## 安装
 
 ```bash
-# 使用 npm
 npm install -D @vureact/compiler-core
-
-# 使用 yarn
-yarn add -D @vureact/compiler-core
-
-# 使用 pnpm
-pnpm add -D @vureact/compiler-core
 ```
 
-## Step 2：编写输入 SFC
-
-`src/components/Counter.vue`
-
-```html
-<template>
-  <section class="counter-card">
-    <h2>{{ props.title || title }}</h2>
-    <p>Count: {{ count }}</p>
-    <button @click="increment">+1</button>
-    <button @click="methods.decrease">-1</button>
-  </section>
-</template>
-
-<script setup lang="ts">
-  // @vr-name: Counter （注：用于告诉编译器，该生成什么组件名）
-  import { computed, ref } from 'vue';
-
-  // 也可以使用宏定义组件名
-  defineOptions({ name: 'Counter' });
-
-  // 定义 props
-  const props = defineProps<{ title?: string }>();
-
-  // 定义 emits
-  const emits = defineEmits<{
-    (e: 'change'): void;
-    (e: 'update', value: number): number;
-  }>();
-
-  const step = ref(1);
-  const count = ref(0);
-  const title = computed(() => `Counter x${step.value}`);
-
-  const increment = () => {
-    count.value += step.value;
-    emits('update', count.value);
-  };
-
-  const methods = {
-    decrease() {
-      count.value -= step.value;
-    },
-  };
-</script>
-
-<style lang="less" scoped>
-  @border-color: #ddd;
-  @border-radius: 8px;
-  @padding-base: 12px;
+## 快速开始
 
-  .counter-card {
-    border: 1px solid @border-color;
-    border-radius: @border-radius;
-    padding: @padding-base;
-  }
-</style>
-```
+👉 **完整教程请访问：[VuReact - 快速开始](https://vureact.top/guide/quick-start.html)**
 
-## Step 3：配置编译器
+### 配置示例
 
 `vureact.config.ts`
 
@@ -120,165 +34,36 @@ pnpm add -D @vureact/compiler-core
 import { defineConfig } from '@vureact/compiler-core';
 
 export default defineConfig({
-  input: 'src',
-  // 关键：排除 Vue 入口文件，避免入口语义冲突
+  input: './src',
   exclude: ['src/main.ts'],
   output: {
     workspace: '.vureact',
-    outDir: 'dist',
-    // 教程场景关闭环境初始化，便于观察纯编译产物
-    // 实际使用时建议开启
-    bootstrapVite: false,
+    outDir: 'react-app',
+    bootstrapVite: true,
   },
 });
 ```
 
-## Step 4：执行编译
-
-### 方式一：使用 npx 命令
-
-在根目录下运行：
-
-```bash
-npx vureact build
-```
-
-### 方式二：使用 npm scripts
-
-在 `package.json` 里添加脚本命令：
-
-```json
-"scripts": {
-  "watch": "vureact watch",
-  "build": "vureact build"
-}
-```
+### 编译命令
 
 ```bash
-npm run build
-```
-
-## Step 5：查看输出目录树
-
-编译后目录（示意）：
-
-```txt
-my-app/
-├─ .vureact/
-│  ├─ cache/
-│  │  └─ _metadata.json
-│  └─ dist/
-│     └─ src/
-│        └─ components/
-│           ├─ Counter.tsx
-│           └─ counter-<hash>.css
-├─ src/
-│  └─ ...
-└─ vureact.config.js
+npx vureact build      # 编译项目
+npx vureact watch      # 监听模式
 ```
 
-## Step 6：对照生成结果
-
-下面是一个格式化后的典型输出（为说明做了轻微简化，实际哈希与属性名以本地产物为准）：
-
-```tsx
-import { memo, useCallback, useMemo } from 'react';
-import { useComputed, useVRef } from '@vureact/runtime-core';
-import './counter-a1b2c3.css';
-
-// 根据 defineProps 和 defineEmits 推导
-type ICounterType = {
-  title?: string;
-  onChange: () => void;
-  onUpdate: (value: number) => number;
-};
-
-// memo 包裹组件
-const Counter = memo((props: ICounterType) => {
-  // ref/computed 转换成了对等的适配 API
-  const step = useVRef(1);
-  const count = useVRef(0);
-  const title = useComputed(() => `Counter x${step.value}`);
-
-  // 自动分析顶层箭头函数依赖，并追加 useCallback 优化
-  const increment = useCallback(() => {
-    count.value += step.value;
-    props.onUpdate?.(count.value); // emits 转换
-  }, [count.value, step.value, props.onUpdate]);
-
-  // 自动分析顶层对象中的依赖，并追加 useMemo 优化
-  const methods = useMemo(
-    () => ({
-      decrease() {
-        count.value -= step.value;
-      },
-    }),
-    [count.value, step.value],
-  );
-
-  return (
-    <>
-      <section className="counter-card" data-css-a1b2c3>
-        <h2 data-css-a1b2c3>{props.title || title.value}</h2>
-        <p data-css-a1b2c3>Count: {count.value}</p>
-        <button onClick={increment} data-css-a1b2c3>
-          +1
-        </button>
-        <button onClick={methods.decrease} data-css-a1b2c3>
-          -1
-        </button>
-      </section>
-    </>
-  );
-});
-
-export default Counter;
-```
-
-CSS 文件内容：
-
-```css
-.counter-card[data-css-a1b2c3] {
-  border: 1px solid #ddd;
-  border-radius: 8px;
-  padding: 12px;
-}
-```
-
-## 关键观察点
-
-1. `// @vr-name: Counter` 这段特殊注释定义了组件名
-2. `defineProps` 和 `defineEmits` 被转换成了 TS 组件类型
-3. 非纯 UI 展示组件，默认会走 `memo` 包装
-4. `ref` / `computed` 被转换为 runtime 适配 API（`useVRef` / `useComputed`）
-5. 模板事件回调会生成符合 React 语义的 `onClick`
-6. 顶层箭头函数自动分析依赖，尝试注入 `useCallback`
-7. 顶层变量声明自动分析依赖，尝试注入 `useMemo`
-8. 对 JSX 中的原 `ref` 状态值补上 `.value`
-9. `less` 样式被编译为 css 代码
-10. `scoped` 样式会生成带哈希的 css 文件，并在元素上标注作用域属性
-
-## 常见问题
-
-- 没排除 Vue 入口文件，如 `src/main.ts`
-- 在非顶层调用会被转换为 Hook 的 API
-- 模板里出现不可分析表达式并被告警
-- 关闭样式预处理且使用 `scoped`，导致作用域失效
-
-更多请查阅官方文档的 [FAQ 章节](https://vureact.top/guide/faq.html)。
-
 ## 生态集成
 
 - **[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 Router](https://router.vureact.top/)**：支持 Vue Router 4.x → React Router DOM 7.9+ 转换
 
 如果确实需要，你可以选择 [☣️混合编写](https://vureact.top/guide/mind-control-readme.html)，以此直接使用 React 生态。
 
+## 常见问题
+
+👉 请查阅[官网 FAQ 章节](https://vureact.top/guide/faq.html)
+
 ## 🔗 链接
 
 - GitHub：<https://github.com/vureact-js/core>
 - Gitee：<https://gitee.com/vureact-js/core>
-- 文档：[https://vureact.top](https://vureact.top/)
-- CodeSandbox 在线案例：
-  - 客户关系管理后台（标准）：<https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/master>
-  - 客户支持协同后台（混写）：<https://codesandbox.io/p/github/vureact-js/example-customer-support-hub/master?import=true>
+- 文档：<https://vureact.top>