Vue jscodeshift Adapter

Common errors

• This may cause things to work incorrectly. Make sure to use the same version for both. (vue-template-compiler@X.Y.Z)

  cause A version mismatch between the installed `vue` package and `vue-template-compiler` (often a transitive dependency) causes conflicts in parsing Vue Single File Components.
  fix Explicitly install `vue-template-compiler` as a dev dependency with the exact same version as your `vue` package: `npm install vue-template-compiler@<YOUR_VUE_VERSION> --save-dev`.

• Error: Your transform did not return a value. Please return the root.toSource().

  cause The jscodeshift transform function, after using `vue-jscodeshift-adapter`, must explicitly return the modified source code using `root.toSource()`.
  fix Ensure your `myCodemod` function (passed to `adapt`) ends with `return root.toSource();`.

• jscodeshift: unknown parser: 'vue'

  cause This error typically indicates that jscodeshift itself does not recognize 'vue' as a valid parser type, or that the `--extensions` flag is misunderstood as a parser instruction. The `vue-jscodeshift-adapter` handles the Vue SFC parsing internally.
  fix You do not need to specify a 'vue' parser. Ensure you are using the `--extensions vue,js` flag correctly with jscodeshift to tell it which file types to process. If you need a specific JavaScript/TypeScript parser for the *script content*, specify it via `--parser=tsx` or `--parser=babel` etc.

Warnings

• gotcha This adapter only processes the `<script>` block within Vue Single File Components. If a `.vue` file lacks a `<script>` block, your jscodeshift transform will not be invoked for that file, and no changes will be applied, even if other blocks (like `<template>` or `<style>`) exist.
  Fix: Ensure all `.vue` files you intend to transform include a `<script>` block, even an empty one (`<script></script>`), if you expect the codemod to run.
• gotcha The package has not been updated in over two years (last release 3.0.0 was March 2022). This means it may not be fully compatible with the latest Vue.js versions (e.g., Vue 3.3+, Vue 3.4+) or recent versions of jscodeshift and its underlying parsers, potentially leading to parsing errors or unexpected behavior with modern JavaScript/TypeScript syntax or newer Vue SFC features.
  Fix: Thoroughly test transformations on a small subset of your codebase before applying broadly. Consider using the more broadly supported 'jscodeshift-adapters' (which was inspired by this project) or other Vue-specific codemod collections like 'vue-codemod' for Vue 2/3 migrations, which may have more active maintenance.
• gotcha Version mismatches with `vue-template-compiler` (a common dependency in the Vue ecosystem) can occur, leading to build errors or incorrect parsing of Vue SFCs. This can happen if `vue-jscodeshift-adapter` or another tool in your dependency tree relies on a specific `vue-template-compiler` version that conflicts with your project's Vue version.
  Fix: Ensure your `vue-template-compiler` version matches your installed `vue` package version. If using `vue-loader >= 10.0`, manually update `vue-template-compiler`. If issues persist, check your dependency tree for conflicting `vue-template-compiler` versions and use `resolutions` or `overrides` in your `package.json` to force a consistent version.

Install

• npm install vue-jscodeshift-adapter npm
• yarn add vue-jscodeshift-adapter yarn
• pnpm add vue-jscodeshift-adapter pnpm

Imports

• adapt
  wrong:

  const adapt = require('vue-jscodeshift-adapter');

  correct:

  import adapt from 'vue-jscodeshift-adapter';

  The primary way to use this library is by importing the default 'adapt' function for ESM projects. While older versions might have supported CommonJS, modern usage and the successor 'jscodeshift-adapters' emphasize ESM.

Quickstart

This quickstart demonstrates how to create a jscodeshift transform, adapt it for Vue SFCs using vue-jscodeshift-adapter, and execute it via the jscodeshift CLI to modify 'var' declarations to 'let' and add comments to script blocks.

import adapt from 'vue-jscodeshift-adapter';

// Define your jscodeshift transform function.
// This example changes 'var' to 'let' and adds a comment.
function myCodemod(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);

  // Transform 'var' declarations to 'let'
  root.find(j.VariableDeclaration, { kind: 'var' })
    .forEach(path => {
      path.node.kind = 'let';
    });

  // Add a comment at the top of the script block
  const firstNode = root.get().node;
  if (firstNode) {
    firstNode.comments = firstNode.comments || [];
    firstNode.comments.unshift(j.commentBlock(' This script was processed by vue-jscodeshift-adapter '));
  }

  return root.toSource();
}

// Export the adapted transform function
export default adapt(myCodemod);

/*
To run this codemod on your Vue and JavaScript files:

1. Save the above code as `transform.js` in your project root.
2. Ensure you have `jscodeshift` installed as a dev dependency:
   `npm install jscodeshift --save-dev`
3. Run the codemod using the jscodeshift CLI:
   `npx jscodeshift your-project-path -t ./transform.js --extensions vue,js`

   Replace `your-project-path` with the actual path to your source files (e.g., `./src`).
   The `--extensions vue,js` flag ensures both Vue SFCs and regular JS files are processed.
*/