{"id":15273,"library":"vue-jscodeshift-adapter","title":"Vue jscodeshift Adapter","description":"vue-jscodeshift-adapter is a utility library designed to bridge jscodeshift, Facebook's JavaScript codemod toolkit, with Vue.js Single File Components (SFCs). It enables developers to apply programmatic code transformations specifically to the `<script>` sections within `.vue` files, which jscodeshift does not natively support. The current stable version is 3.0.0. This package was an early solution in the Vue codemod space, heavily inspiring the 'jscodeshift-adapters' project. While jscodeshift itself receives regular updates, vue-jscodeshift-adapter appears to be in a maintenance-only state with its last release over two years ago. Its primary differentiator is its targeted extraction and re-insertion of Vue SFC script content, allowing standard jscodeshift transforms to operate on Vue-specific logic, distinguishing it from general jscodeshift usage or other Vue migration tools like 'vue-codemod' that offer pre-built transformations.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/psalaets/vue-jscodeshift-adapter","tags":["javascript","vue","sfc","component","refactor","codemod","jscodeshift"],"install":[{"cmd":"npm install vue-jscodeshift-adapter","lang":"bash","label":"npm"},{"cmd":"yarn add vue-jscodeshift-adapter","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-jscodeshift-adapter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the underlying codemod runner; this adapter provides the bridge for Vue SFCs.","package":"jscodeshift","optional":false},{"reason":"Used internally by Vue tools to parse SFCs; version mismatches can cause issues.","package":"vue-template-compiler","optional":true}],"imports":[{"note":"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.","wrong":"const adapt = require('vue-jscodeshift-adapter');","symbol":"adapt","correct":"import adapt from 'vue-jscodeshift-adapter';"}],"quickstart":{"code":"import adapt from 'vue-jscodeshift-adapter';\n\n// Define your jscodeshift transform function.\n// This example changes 'var' to 'let' and adds a comment.\nfunction myCodemod(file, api) {\n  const j = api.jscodeshift;\n  const root = j(file.source);\n\n  // Transform 'var' declarations to 'let'\n  root.find(j.VariableDeclaration, { kind: 'var' })\n    .forEach(path => {\n      path.node.kind = 'let';\n    });\n\n  // Add a comment at the top of the script block\n  const firstNode = root.get().node;\n  if (firstNode) {\n    firstNode.comments = firstNode.comments || [];\n    firstNode.comments.unshift(j.commentBlock(' This script was processed by vue-jscodeshift-adapter '));\n  }\n\n  return root.toSource();\n}\n\n// Export the adapted transform function\nexport default adapt(myCodemod);\n\n/*\nTo run this codemod on your Vue and JavaScript files:\n\n1. Save the above code as `transform.js` in your project root.\n2. Ensure you have `jscodeshift` installed as a dev dependency:\n   `npm install jscodeshift --save-dev`\n3. Run the codemod using the jscodeshift CLI:\n   `npx jscodeshift your-project-path -t ./transform.js --extensions vue,js`\n\n   Replace `your-project-path` with the actual path to your source files (e.g., `./src`).\n   The `--extensions vue,js` flag ensures both Vue SFCs and regular JS files are processed.\n*/","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"This may cause things to work incorrectly. Make sure to use the same version for both. (vue-template-compiler@X.Y.Z)"},{"fix":"Ensure your `myCodemod` function (passed to `adapt`) ends with `return root.toSource();`.","cause":"The jscodeshift transform function, after using `vue-jscodeshift-adapter`, must explicitly return the modified source code using `root.toSource()`.","error":"Error: Your transform did not return a value. Please return the root.toSource()."},{"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.","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.","error":"jscodeshift: unknown parser: 'vue'"}],"ecosystem":"npm"}