Skip to content

Commit 7942160

Browse files
Haixing-HuHaixing-Hu
committed
docs: refine the README
1 parent 12c643d commit 7942160

File tree

2 files changed

+205
-45
lines changed

2 files changed

+205
-45
lines changed

‎README.md

Lines changed: 105 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# vue3-class-component
22

3+
[![npm package](https://img.shields.io/npm/v/@haixing_hu/vue3-class-component.svg)](https://npmjs.com/package/@haixing_hu/vue3-class-component)
34
[![License](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
45
[![中文文档](https://img.shields.io/badge/文档-中文版-blue.svg)](README.zh_CN.md)
56
[![CircleCI](https://dl.circleci.com/status-badge/img/gh/Haixing-Hu/vue3-class-component/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/Haixing-Hu/vue3-class-component/tree/master)
@@ -9,14 +10,16 @@ This library allows you to create your [Vue] components using the class-style sy
910
It draws heavy inspiration from [vue-class-component], with a few notable differences:
1011

1112
- It supports [Vue] v3.x.x (currently v3.3.4).
12-
- It's written in pure JavaScript rather than TypeScript, distinguishing it
13-
from [vue-facing-decorator].
13+
- Unlike [vue-facing-decorator], it's written in pure JavaScript rather than TypeScript,
14+
eliminating the need for TypeScript configuration.
1415
- It adopts the most recent (as of May 2023) [stage 3 proposal of JavaScript decorators]
1516
and [stage 3 proposal of JavaScript decorator metadata].
1617
- It offers a set of commonly used decorators for class-style Vue components, such as
17-
`@Prop`, `@Watch`, `@Provide`, and `@Inject` (for more details, see the
18+
`@Prop`, `@Watch`, `@Provide`, and `@Inject` (for more details, refer to the
1819
[Predefined Decorators](#predefined-decorators) section). In essence, it
1920
combines the functionality of [vue-class-component] and [vue-property-decorator].
21+
- Offer both UMD and ESM bundling formats, providing support for both [webpack] and [vite].
22+
For more details, refer to the [Configuration](#configuration) section.
2023
- It has undergone extensive unit testing, achieving a remarkable 100% code coverage.
2124
- The code has undergone a complete rewrite, and the functionality of decorators has been redesigned for improved coherence and efficiency.
2225

@@ -50,28 +53,105 @@ This library uses the most recent (currently May 2023)
5053
[Babel] with [@babel/plugin-transform-class-properties] and the
5154
[@babel/plugin-proposal-decorators] plugins.
5255

53-
A possible [Babel] configuration file `babel.config.json` is as follows:
54-
```json
55-
{
56-
"presets": [
57-
"@babel/preset-env"
58-
],
59-
"plugins": [
60-
"@babel/plugin-transform-runtime",
61-
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
62-
"@babel/plugin-transform-class-properties"
63-
]
64-
}
65-
```
66-
67-
**IMPORTANT NOTE:** To support the [stage 3 proposal of JavaScript decorator metadata],
56+
**NOTE:** To support the [stage 3 proposal of JavaScript decorator metadata],
6857
the version of the [Babel] plugin [@babel/plugin-proposal-decorators] must be
6958
at least `7.23.0`.
7059

71-
To learn how to create a new Vue.js project and utilize [vue3-class-component], please consult the following:
72-
73-
- Demo project created by [vue-cli] and [webpack]: [vue3-class-component-demo-webpack]
74-
- Demo project created by [create-vue] and [vite]: [vue3-class-component-demo-vite]
60+
### <span id="webpack">Bundling with [webpack]</span>
61+
62+
1. Install the required dependencies:
63+
2. Configure [Babel] by using the [@babel/plugin-transform-class-properties]
64+
and [@babel/plugin-proposal-decorators] plugins. A possible [Babel]
65+
configuration file `babelrc.json` is as follows:
66+
```json
67+
{
68+
"presets": [
69+
"@babel/preset-env"
70+
],
71+
"plugins": [
72+
"@babel/plugin-transform-runtime",
73+
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
74+
"@babel/plugin-transform-class-properties"
75+
]
76+
}
77+
```
78+
79+
For detailed configuration instructions, you can refer to:
80+
- A sample project created with [vue-cli] and [webpack]: [vue3-class-component-demo-webpack]
81+
82+
### <span id="vite">Bundling with [vite]</span>
83+
84+
1. Install the required dependencies:
85+
```shell
86+
yarn add @haixing_hu/vue3-class-component
87+
yarn add --dev @babel/core @babel/runtime @babel/preset-env
88+
yarn add --dev @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties @babel/plugin-transform-runtime
89+
```
90+
2. Configure [Babel] by using [@babel/plugin-transform-class-properties] and
91+
[@babel/plugin-proposal-decorators] plugins. A possible [Babel] configuration
92+
file `babelrc.json` is as follows:
93+
```json
94+
{
95+
"presets": [
96+
["@babel/preset-env", { "modules": false }]
97+
],
98+
"plugins": [
99+
"@babel/plugin-transform-runtime",
100+
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
101+
"@babel/plugin-transform-class-properties"
102+
]
103+
}
104+
```
105+
**Note:** When bundling with [vite], make sure to set the `modules` parameter
106+
of `@babel/preset-env` to `false`.
107+
3. Configure [vite] by modifying the `vite.config.js` file to add support for
108+
[Babel]. A possible `vite.config.js` file is as follows:
109+
```js
110+
import { fileURLToPath, URL } from 'node:url';
111+
import { defineConfig } from 'vite';
112+
import vue from '@vitejs/plugin-vue';
113+
import * as babel from '@babel/core';
114+
115+
// A very simple Vite plugin support babel transpilation
116+
const babelPlugin = {
117+
name: 'plugin-babel',
118+
transform: (src, id) => {
119+
if (/\.(jsx?|vue)$/.test(id)) { // the pattern of the file to handle
120+
return babel.transform(src, {
121+
filename: id,
122+
babelrc: true,
123+
});
124+
}
125+
},
126+
};
127+
// https://vitejs.dev/config/
128+
export default defineConfig({
129+
plugins: [
130+
vue({
131+
script: {
132+
babelParserPlugins: ['decorators'], // must enable decorators support
133+
},
134+
}),
135+
babelPlugin, // must be after the vue plugin
136+
],
137+
resolve: {
138+
alias: {
139+
'@': fileURLToPath(new URL('./src', import.meta.url)),
140+
},
141+
},
142+
});
143+
```
144+
**Note:** In the above configuration file, we've implemented a simple [Vite]
145+
plugin to transpile the code processed by the [vite-plugin-vue] plugin using
146+
[Babel]. Although there's a [vite-plugin-babel] plugin that claims to add
147+
[Babel] support to [vite], we found it doesn't correctly handle [vue] Single
148+
File Components (SFCs). After closely examining its source code, we
149+
determined that to achieve correct transpilation, we need to apply [Babel]
150+
after [vite-plugin-vue] processes the source code. Therefore, the very
151+
simple plugin function above suffices for our needs.
152+
153+
For detailed configuration instructions, you can refer to:
154+
- A sample project created with [create-vue] and [vite]: [vue3-class-component-demo-vite]
75155

76156
## <span id="usage-example">Usage Example</span>
77157

@@ -716,4 +796,6 @@ or setter of the component class.
716796
[working with reactivity]: https://vuejs.org/guide/components/provide-inject#working-with-reactivity
717797
[vue3-class-component]: https://github.com/Haixing-Hu/vue3-class-component
718798
[vue3-class-component-demo-webpack]: https://github.com/Haixing-Hu/vue3-class-component-demo-webpack
719-
[vue3-class-component-demo-vite]: https://github.com/Haixing-Hu/vue3-class-component-demo-vite
799+
[vue3-class-component-demo-vite]: https://github.com/Haixing-Hu/vue3-class-component-demo-vite
800+
[vite-plugin-vue]: https://www.npmjs.com/package/@vitejs/plugin-vue
801+
[vite-plugin-babel]: https://www.npmjs.com/package/vite-plugin-babel

‎README.zh_CN.md

Lines changed: 100 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
11
# vue3-class-component
22

3+
[![npm package](https://img.shields.io/npm/v/@haixing_hu/vue3-class-component.svg)](https://npmjs.com/package/@haixing_hu/vue3-class-component)
34
[![License](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
45
[![English Document](https://img.shields.io/badge/Document-English-blue.svg)](README.md)
56
[![CircleCI](https://dl.circleci.com/status-badge/img/gh/Haixing-Hu/vue3-class-component/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/Haixing-Hu/vue3-class-component/tree/master)
67
[![Coverage Status](https://coveralls.io/repos/github/Haixing-Hu/vue3-class-component/badge.svg?branch=master)](https://coveralls.io/github/Haixing-Hu/vue3-class-component?branch=master)
78

8-
99
这个库允许您使用类式语法创建您的 [Vue] 组件。它从 [vue-class-component] 得到了很多灵感，但有一些显著的区别：
1010

1111
- 它支持 [Vue] v3.x.x（当前版本为 v3.3.4）。
12-
- 它使用纯 JavaScript 而非 TypeScript，这与 [vue-facing-decorator] 不同。
12+
- 与 [vue-facing-decorator] 不同，它使用纯 JavaScript 而非 TypeScript 编写，不再需要配置使用 TypeScript。
1313
- 它采用了最新的（截止到2023年5月） [JavaScript 装饰器第3阶段提案] 和
1414
[JavaScript 装饰器元数据第3阶段提案]。
1515
- 它提供了用于类式 Vue 组件的常用装饰器，如 @Prop、@Watch、@Provide 和 @Inject（更多详情
1616
请参阅[预定义装饰器](#predefined-decorators)部分）。简而言之，它结合了 [vue-class-component] 和
1717
[vue-property-decorator] 的功能。
18-
- 它经过了详细的单元测试，代码覆盖率达到了100%。
19-
- 代码已经全面重写，装饰器功能经过重新设计，更加合理。
18+
- 同时提供 UMD 和 ESM 打包格式，支持[webpack]和[vite]。更多详细信息，请参阅[配置](#configuration)部分。
19+
- 经过详细单元测试，代码覆盖率达到了100%。
20+
- 代码全面重写，装饰器功能经过重新设计，更加合理。
2021

2122
## 目录
2223

@@ -48,26 +49,101 @@ npm install @haixing_hu/vue3-class-component
4849
使用 [@babel/plugin-transform-class-properties] 和
4950
[@babel/plugin-proposal-decorators] 插件。
5051

51-
一个可能的 [Babel] 配置文件 `babel.config.json` 如下：
52-
```json
53-
{
54-
"presets": [
55-
"@babel/preset-env"
56-
],
57-
"plugins": [
58-
"@babel/plugin-transform-runtime",
59-
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
60-
"@babel/plugin-transform-class-properties"
61-
]
62-
}
63-
```
64-
65-
**重要说明:** 为了支持 [JavaScript 装饰器元数据第3阶段提案],
52+
**注意：** 为了支持 [JavaScript 装饰器元数据第3阶段提案],
6653
插件 [@babel/plugin-proposal-decorators] 的版本号必须至少为 `7.23.0`。
6754

68-
要了解如何创建一个新的Vue.js项目并使用[vue3-class-component]，请查看以下内容：
69-
55+
### <span id="webpack">使用 [webpack] 打包</span>
56+
57+
1. 安装需要的依赖：
58+
```bash
59+
yarn add @haixing_hu/vue3-class-component
60+
yarn add --dev @babel/core @babel/runtime @babel/preset-env
61+
yarn add --dev @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties @babel/plugin-transform-runtime
62+
```
63+
2. 配置 [Babel]，使用 [@babel/plugin-transform-class-properties] 和
64+
[@babel/plugin-proposal-decorators] 插件。一个可能的 [Babel] 配置文件 `babelrc.json` 如下：
65+
```json
66+
{
67+
"presets": [
68+
"@babel/preset-env"
69+
],
70+
"plugins": [
71+
"@babel/plugin-transform-runtime",
72+
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
73+
"@babel/plugin-transform-class-properties"
74+
]
75+
}
76+
```
77+
78+
详细配置过程可以参考：
7079
- 使用 [vue-cli] 和 [webpack] 创建的演示项目：[vue3-class-component-demo-webpack]
80+
81+
### <span id="vite">使用 [vite] 打包</span>
82+
83+
1. 安装需要的依赖：
84+
```bash
85+
yarn add @haixing_hu/vue3-class-component
86+
yarn add --dev @babel/core @babel/runtime @babel/preset-env
87+
yarn add --dev @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties @babel/plugin-transform-runtime
88+
```
89+
2. 配置 [Babel]，使用 [@babel/plugin-transform-class-properties] 和
90+
[@babel/plugin-proposal-decorators] 插件。一个可能的 [Babel] 配置文件 `babelrc.json` 如下：
91+
```json
92+
{
93+
"presets": [
94+
["@babel/preset-env", { "modules": false }]
95+
],
96+
"plugins": [
97+
"@babel/plugin-transform-runtime",
98+
["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
99+
"@babel/plugin-transform-class-properties"
100+
]
101+
}
102+
```
103+
**注意：** 使用 [vite] 打包需要将 `@babel/preset-env` 的参数 `modules` 设置为 `false`。
104+
3. 配置 [vite]，修改 `vite.config.js` 文件，使其支持 [Babel]。一个可能的 `vite.config.js` 文件如下：
105+
```javascript
106+
import { fileURLToPath, URL } from 'node:url';
107+
import { defineConfig } from 'vite';
108+
import vue from '@vitejs/plugin-vue';
109+
import * as babel from '@babel/core';
110+
111+
// A very simple Vite plugin support babel transpilation
112+
const babelPlugin = {
113+
name: 'plugin-babel',
114+
transform: (src, id) => {
115+
if (/\.(jsx?|vue)$/.test(id)) { // the pattern of the file to handle
116+
return babel.transform(src, {
117+
filename: id,
118+
babelrc: true,
119+
});
120+
}
121+
},
122+
};
123+
// https://vitejs.dev/config/
124+
export default defineConfig({
125+
plugins: [
126+
vue({
127+
script: {
128+
babelParserPlugins: ['decorators'], // must enable decorators support
129+
},
130+
}),
131+
babelPlugin, // must after the vue plugin
132+
],
133+
resolve: {
134+
alias: {
135+
'@': fileURLToPath(new URL('./src', import.meta.url)),
136+
},
137+
},
138+
});
139+
```
140+
**注意：** 在上面配置文件中我们实现了一个简单的 [Vite] 插件用于将 [vite-plugin-vue]
141+
插件处理过的代码通过 [babel] 转译。虽然有个 [vite-plugin-babel] 插件声称可以让 [vite]
142+
支持 [babel]，但我们发现它无法正确处理 [vue] 的 SFC 格式 (`*.vue`格式文件）。仔细研究
143+
它的源码后，我们发现要实现正确的转译，必须在 [vite-plugin-vue] 插件处理过源码之后再使用
144+
[babel] 进行转译，因此只需上面非常简单的插件函数即可实现我们需要的功能。
145+
146+
详细配置过程可以参考：
71147
- 使用 [create-vue] 和 [vite] 创建的演示项目：[vue3-class-component-demo-vite]
72148
73149
## <span id="usage-example">使用示例</span>
@@ -654,4 +730,6 @@ export default toVue(MyComponent);
654730
[使用响应式]: https://vuejs.org/guide/components/provide-inject#working-with-reactivity
655731
[vue3-class-component]: https://github.com/Haixing-Hu/vue3-class-component
656732
[vue3-class-component-demo-webpack]: https://github.com/Haixing-Hu/vue3-class-component-demo-webpack
657-
[vue3-class-component-demo-vite]: https://github.com/Haixing-Hu/vue3-class-component-demo-vite
733+
[vue3-class-component-demo-vite]: https://github.com/Haixing-Hu/vue3-class-component-demo-vite
734+
[vite-plugin-vue]: https://www.npmjs.com/package/@vitejs/plugin-vue
735+
[vite-plugin-babel]: https://www.npmjs.com/package/vite-plugin-babel

0 commit comments

Comments
 (0)