Skip to content

Latest commit

 

History

History
218 lines (181 loc) · 18.3 KB

README.md

File metadata and controls

218 lines (181 loc) · 18.3 KB
Raw

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

  • Basic testing setup and a dummy CLI
  • Support applying jscodeshift codemods to .vue files
  • Provide a programmatic interface for usage in vue-cli-plugin-vue-next
  • 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)
  • 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

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
  • 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
  • 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

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.

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.

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