vue-codemod

Current status: experimental

This repository contains a collection of codemod scripts for use with JSCodeshift that help update Vue.js APIs.

Inspired by react-codemod.

Command Line Usage

npx vue-codemod <path> -t <transformation> --params [transformation params] [...additional options]

• transformation (required) - name of transformation, see available transformations below; or you can provide a path to a custom transformation module.
• path (required) - files or directory to transform.
• --params (optional) - additional transformation specific args.

Programmatic API

• runTransformation(fileInfo, transformation, params)

Roadmap

• [x] Basic testing setup and a dummy CLI
• [x] Support applying jscodeshift codemods to .vue files
• [x] Provide a programmatic interface for usage in vue-cli-plugin-vue-next
• [x] Set up tests
• [ ] (WIP) Implement the transformations described below for migration usage
• [ ] Built-in transformations need to support TypeScript
• [ ] Built-in transformations need to support module systems other than ES module, and those without modules
• [ ] Define an interface for transformation of template blocks (may use vue-eslint-parser for this)
• [x] A playground for writing transformations - yarn playground and visit http://localhost:3000

Included Transformations

Migrating from Vue 2 to Vue 3

The migration path (to be integrated in a new version of vue-migration-helper):

1. Install eslint-plugin-vue@7, turn on the vue3-essential category (maybe a few exceptions like vue/no-deprecated-dollar-scopedslots-api)
2. Run eslint --fix to fix all auto-fixable issues; if there are any remaining errors, fix them manually
3. Run the codemods below
4. Install vue@3, vue-loader@16, etc.
5. Make sure to use the compat build of vue@3
6. Serve the app in development mode, fix the runtime deprecation warnings

Note: even though most of the migration process can be automated, please be aware there might still be subtle differences between Vue 3 and Vue 2 runtime, and the codemods may have uncovered edge cases. Please double check before deploying your Vue 3 app into production.

Legend of annotations:

| Mark | Description | | ---- | ---------------------------------------------------- | | 🔴 | work not started | | 🔵 | needs to or can be implemented in the compat runtime |

Fixable in ESLint

• RFC05: Replace v-bind's .sync with a v-model argument
  • Can be detected and fixed by the vue/no-deprecated-v-bind-sync ESLint rule
• RFC14: Remove keyCode support in v-on
  • Can be detected and fixed by the vue/no-deprecated-v-on-number-modifiers ESLint rule
  • config.keyCode can be supported in the compat build. It is also detectable with the vue/no-deprecated-vue-config-keycodes ESLint rule
• RFC19: Remove data object declaration
  • Can be detected and fixed by the vue/no-shared-component-data and the vue/no-deprecated-data-object-declaration ESLint rules

Codemods

• RFC01: New slot syntax and RFC06: Slots unification
  • Can be detected and partially fixed by the vue/no-deprecated-slot-attribute and vue/no-deprecated-slot-scope-attribute
  • During the transition period, with the 2 ESLint rules enabled, it will warn users when they use this.$slots, recommending this.$scopedSlots as a replacement
  • When upgrading to Vue 3, replace all .$scopedSlots occurrences with .$slots (should pass the abovementioned ESLint checks before running this codemod) (implemented as scoped-slots-to-slots)
• RFC04: Global API treeshaking & RFC09: Global mounting/configuration API change
  • implemented as new-global-api
  • import Vue from 'vue' -> import * as Vue from 'vue' (implemented as vue-as-namespace-import)
  • Vue.extend -> defineComponent (implemented as define-component)
  • new Vue() -> Vue.createApp() (implemented as new-vue-to-create-app)
    • new Vue({ el }), new Vue().$mount -> Vue.createApp().mount
    • new HelloWorld({ el }), new HelloWorld().$mount -> createApp(HelloWorld).mount
  • render(h) -> render() and import { h } from 'vue' (implemented as remove-contextual-h-from-render)
  • Vue.config.productionTip -> removed (implemented as remove-production-tip)
  • 🔴 Some global APIs now can only be used on the app instances, while it's possible to support the legacy usage in a compat build, we will provide a codemod to help migration. (global-to-per-app-api)
    • Vue.config, Vue.use, Vue.mixin, Vue.component, Vue.directive, etc -> app.** (It's possible to provide a runtime compatibility layer for single-root apps)
    • Vue.prototype.customProperty -> app.config.globalProperties.customProperty
    • Vue.config.ignoredElements -> app.config.isCustomElement
    • The migration path would be a two-pass approach:
      1. Scan the entire project to collect all the usages of the abovementioned global properties / methods
      2. Depending on the result of the first scan:
         1. If there's only one entry file using these global APIs, then transform it;
         2. If there's exactly one entry file and one root instance, but several other files are also using Vue.*, then transform the entry file to export the root instance, import it in other files and transform them with the imported root instance;
         3. If there are more than one entry file or root instances, then the user needs to manually export the root instances, re-apply this codemod to those non-entry files with an argument designating the root instance.
  • 🔵 Detect and warn on optionMergeStrategies behavior change
• RFC07: Functional and async components API change
  • 🔵 a compatibility mode can be provided for functional components for one-at-a-time migration
  • Can be detected by the vue/no-deprecated-functional-template ESLint rule
  • 🔴 SFCs using <template functional> should be converted to normal SFCs
• RFC08: Render function API change
  • Template users won't be affected
  • JSX plugin will be rewritten to cover most use cases (work-in-progress, available at https://github.com/vueComponent/jsx/)
  • 🔴 For Users who manually write render functions using h
    • 🔵 It's possible to provide a compat plugin that patches render functions and make them expose a 2.x compatible arguments, and can be turned off in each component for a one-at-a-time migration process.
    • 🔴 It's also possible to provide a codemod that auto-converts h calls to use the new VNode data format, since the mapping is pretty mechanical.
  • 🔴 Functional components using context will likely have to be manually migrated, but a similar adaptor can be provided.
• RFC12: Custom directive API change
  • bind -> beforeMount
  • inserted -> mounted
  • remove update hook and insert a comment to note the user about the change
  • componentUpdated -> updated
  • unbind -> unmounted
  • 🔴 VNode interface change (a runtime compat plugin is also possible, see the notes for RFC08)
• RFC13: Composition API
  • import ... from '@vue/composition-api' -> import ... from 'vue' (implemented as import-composition-api-from-vue)
  • There are some subtle differences between the plugin and Vue 3 implementation, see https://github.com/vuejs/composition-api#limitations for more details.
• RFC16: Remove inline-template
  • Can be detected by the vue/no-deprecated-inline-template ESLint rule
  • 🔴 Possible alternatives are addressed in the RFC
• RFC25: Built-in <Teleport> component
  • Can be detected by the vue/no-reserved-component-names ESLint rule
  • 🔴 A codemod can be implemented to rename all <Teleport> components to some other name like <TeleportComp>.
• 🔴 RFC26: New async component API
  • 🔵 In the compat build, it is possible to check the return value of functional components and warn legacy async components usage. This should cover all Promise-based use cases.
  • 🔴 The syntax conversion is mechanical and can be performed via a codemod. The challenge is in determining which plain functions should be considered async components. Some basic heuristics can be used (note this may not cover 100% of the existing usage):
    • Arrow functions that returns dynamic import call to .vue files
    • Arrow functions that returns an object with the component property being a dynamic import call.
  • The only case that cannot be easily detected is 2.x async components using manual resolve/reject instead of returning promises. Manual upgrade will be required for such cases but they should be relatively rare.
• 🔴 RFC30: Add emits component option
  • There could be potential naming conflicts with existing component-level emits options, so we need to scan and warn on such usages
  • To better utilize the new emits option, we can provide a codemod that automatically scans all instances of $emit calls in a component and generate the emits option
• Vuex 3.x to 4
  • implemented as in combination of new-global-api and vuex-v4
  • Vue.use(Vuex) & new Vue({ store }) -> app.use(store)
  • new Store() -> createStore()
• Vue Router 3.x to 4
  • implemented as in combination of new-global-api and vue-router-v4
  • Vue.use(VueRouter) & new Vue({ router }) -> app.use(router)
  • new VueRouter() -> createRouter()
  • mode: 'history', base: BASE_URL etc. -> history: createWebHistory(BASE_URL) etc.
  • 🔴 RFC21: Scoped slot API for router-link
  • 🔴 RFC28: Change active and exact-active behavior for router-link
• vue-class-component 7.x to 8
  • import { Component } from 'vue-class-component' -> import { Options as Component } from 'vue-class-component'
  • 🔴 import Vue from 'vue' -> import { Vue } from 'vue-class-component' (Need to avoid name collision if there's any reference to Vue besides extends Vue)
  • 🔴 Component.registerHooks -> Vue.registerHooks

Breaking Changes that Can Only Be Manually Migrated

• RFC17: Changed behavior when using transition as root
  • Can be detected by the vue/require-toggle-inside-transition ESLint rule
• RFC22: Merge meta fields from parent to child in RouteLocation
  • Seems no codemod or ESLint rule is applicable to this breaking change
• RFC24: Attribute coercion behavior change
  • Codemod is not likely to help in this case
• RFC31: Attribute Fallthrough + Functional Component Updates
  • Warn of every $listeners and .native usage
• Subtle differences between @vue/composition-api and the Vue 3 implementation are listed in the @vue/composition-api README
• The precedence of v-if and v-for have been flipped when using both on the same element.
• Warn for mixing v-for and ref.
• Warn about deprecated instance methods and properties: $destroy, $children

RFCs that May Need Amendments to Simplify the Migration

Note: there are just rough ideas. Amendments may or may not be proposed, depending on the implementation progress of this repo.

• 🔵 RFC04: Global API treeshaking & RFC09: Global mounting/configuration API change
  • Vue.extend can be supported in a compat runtime as an alias to defineComponent
• 🔵 RFC11: Component v-model API change
  • I don't have a clear idea on how to progressively migrate the v-model API because both the author and consumer of the components need to change their ways to use this API, according to the current RFC. So we might need a compatibility layer in the runtime.

Other Opt-In Changes

These features are only deprecated but still supported in the compatiblity builds. There will be runtime warnings and ESLint rules to detect their usages. Some of them can be automatically migrated with the help of codemods.

• RFC15: Remove filters
  • Can be detected by the vue/no-deprecated-filter ESLint rule
• 🔴 RFC18: Transition class name adjustments
  • For <transition> components with custom enter-class or leave-class:
    • enter-class -> enter-from-class
    • leave-class -> leave-from-class
  • Otherwise, there are two possible solutions:
    • Change every .v-enter and .v-leave selector in the stylesheets to .v-enter-from and .v-leave-from
    • Or, attach enter-from-class="v-enter v-enter-from" leave-from-class="v-leave v-leave-from" to these <transition> components. Users can delete these attributes after they updated the corresponding stylesheets
• RFC20: Events API Change
  • Can be detected by the vue/no-deprecated-events-api ESLint rule
  • 🔴 A codemod can be implemented to use other libraries like tiny-emitter for the events API
• RFC23-scoped-styles-changes
  • The new behavior should be opt-in
• RFC27: Custom Elements Interop Improvements
  • (Covered by the Global API RFCs): Vue.config.ignoredElements -> app.config.isCustomElement
  • 🔴 Vue 2 non-<component> tags with is usage ->
    • <component is> (for SFC templates).
    • v-is (for in-DOM templates).
  • The vue/no-deprecated-html-element-is ESLint rule can be used to detect usage for is usage on built-in HTML tags.
• set and delete instance or global methods will be supported only in IE compat builds.
  • implemented as remove-vue-set-and-delete

Generic Transformations

Aside from migrating Vue 2 apps to Vue 3, this repository also includes some generic transformations that can help clean up your codebase.

• remove-trivial-root
  • this transformation removes trivial root components like { render: () => h(App) } and use App as the direct root
• define-component
  • --param.useCompositionAPI: false by default. When set to true, it will import the defineComponent helper from @vue/composition-api instead of vue
  • this transformation adds defineComponent() wrapper to .vue file exports, and replaces Vue.extend calls to defineComponent

Custom Transformation

See https://github.com/facebook/jscodeshift#transform-module

Post Transformation

• Running transformations will generally ruin the formatting of your files. A recommended way to solve that problem is by using Prettier or eslint --fix.
• Even after running prettier its possible to have unnecessary new lines added/removed. This can be solved by ignoring white spaces while staging the changes in git.

git diff --ignore-blank-lines | git apply --cached