Skip to content

Commit 341fa38

Browse files
committed
chore: document ts and alt strategy for compat build
1 parent fb96a85 commit 341fa38

File tree

1 file changed

+28
-2
lines changed

1 file changed

+28
-2
lines changed

packages/vue-compat/README.md

+28-2
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44

55
`@vue/compat` (aka "the migration build") is a build of Vue 3 that provides configurable Vue 2 compatible behavior.
66

7-
The migration build runs in Vue 2 mode by default - most public APIs behave exactly like Vue 2, with only [a few exceptions](TODO). Usage of features that have changed or been deprecated in Vue 3 will emit runtime warnings. A feature's compatibility can be enabled/disabled on a per-component basis.
7+
The migration build runs in Vue 2 mode by default - most public APIs behave exactly like Vue 2, with only [a few exceptions](#incompatible). Usage of features that have changed or been deprecated in Vue 3 will emit runtime warnings. A feature's compatibility can be enabled/disabled on a per-component basis.
88

99
### Intended Use Cases
1010

11-
- Upgrading a Vue 2 application to Vue 3 (with limitations)
11+
- Upgrading a Vue 2 application to Vue 3 (with limitations - see below).
1212
- Migrate a library to support Vue 3
1313
- For experienced Vue 2 developers who have not tried Vue 3 yet, the migration build can be used in place of Vue 3 to help learn the difference between versions.
1414

@@ -195,6 +195,30 @@ The following workflow walks through the steps of migrating an actual Vue 2 app
195195

196196
[Example commit](https://github.com/vuejs/vue-hackernews-2.0/commit/9beb45490bc5f938c9e87b4ac1357cfb799565bd)
197197

198+
199+
## Alternative Workflow
200+
201+
The above workflow is "inside-out": it tries to get the app running in Vue 2 mode first, and then gradually move parts over to Vue 3. However, it's possible that your app simply won't run at all due to potential complexity.
202+
203+
In such cases, an alternative "outside-in" strategy would be to start a fresh app running the migration build in [Vue 3 mode](#vue-3-mode), then gradually move parts from the old app into the new app. Existing components can be moved into the new app under Vue 2 mode (see [per component config](#per-component-config)) and then migrated to Vue 3 mode individually. This strategy is closer to a partial rewrite, but you should still be able to reuse most of the code.
204+
205+
## TypeScript Support
206+
207+
The `@vue/compat` package does not ship types, since we will be importing from the aliased `vue` package. TypeScript will be using the Vue 3 types from the `vue` package.
208+
209+
Vue 3 no longer provides a default export - so if you want to get type support for `import Vue from 'vue'` you will need to shim the default export with:
210+
211+
```ts
212+
// shim.d.ts
213+
declare module 'vue' {
214+
import { CompatVue } from '@vue/runtime-dom'
215+
const Vue: CompatVue
216+
export default Vue
217+
}
218+
```
219+
220+
Note the `CompatVue` type does not provide options API `this` type inference for `new Vue()` and `Vue.extend` - to get `this` type inference inside compoent options, update to use [`defineComponent`](https://v3.vuejs.org/api/global-api.html#definecomponent) instead.
221+
198222
## Compat Configuration
199223

200224
### Global Config
@@ -211,6 +235,8 @@ configureCompat({
211235
})
212236
```
213237

238+
### Vue 3 Mode
239+
214240
Alternatively, the entire application can default to Vue 3 behavior, with only certain compat features enabled:
215241

216242
```js

0 commit comments

Comments
 (0)