vue-metamorph

library3.3.4jsnpmunverified

Vue Metamorph is a robust codemod framework designed for manipulating Abstract Syntax Trees (ASTs) across various file types, including JavaScript, TypeScript, Vue Single File Components (SFCs), CSS, SCSS, LESS, SASS, and Stylus. Currently stable at version 3.3.4, the library sees active development with frequent dependency updates and minor feature enhancements, as evidenced by its recent changelog. It differentiates itself by providing a comprehensive, AST-based approach to large-scale code changes in Vue projects, addressing limitations of regex-based transformations. Unlike some alternatives, Vue Metamorph offers a full recast-like experience for entire Vue SFCs, allowing for reliable and precise manipulation of script, template, and style sections.

devops

npm install vue-metamorph

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-METAMORPH

vue-metamorph

devopsjavascriptv3.3.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Codemod

✓ import type { Codemod } from 'vue-metamorph';

This type is used when defining a codemod plugin. The plugin itself is then typically run via the `vue-metamorph` CLI.

AST

✓ import type { AST } from 'vue-eslint-parser';

✗ import type { AST } from 'vue-metamorph';

Vue Metamorph re-exports types from underlying parsers. For Vue template ASTs, it leverages `vue-eslint-parser` types. Direct import from `vue-metamorph` for `AST` might not be correct as it's a wrapper.

builders

✓ import { builders } from 'ast-types-x';

✗ import { builders } from 'recast';

When creating new AST nodes within a codemod, `builders` from `ast-types-x` should be used. This replaces the `recast` or original `ast-types` builders used in older versions.

Demonstrates defining a Vue Metamorph codemod to rename a Vue component and add an attribute to its usage in a Vue SFC template, and how to execute it via the CLI.

import type { Codemod } from 'vue-metamorph'; import { builders } from 'ast-types-x'; // This codemod renames all 'my-component' components to 'new-component' // and adds a new 'data-migrated' attribute to them. export const codemod: Codemod = { transform({ scriptASTs, templateAST, filename }) { if (!templateAST) { return; } let transformCount = 0; templateAST.traverse({ enter(node) { // Find <my-component> if (node.type === 'VElement' && node.name === 'my-component') { node.name = 'new-component'; // Add a new attribute: data-migrated="true" const migratedAttr = builders.vAttribute( builders.vDirectiveKey(builders.vIdentifier('data-migrated')), builders.vLiteral('true') ); node.startTag.attributes.push(migratedAttr); transformCount++; } } }); if (transformCount > 0) { console.log(`Transformed ${transformCount} instances in ${filename}`); return true; // Indicate that changes were made } return false; }, }; // To run this codemod: // 1. Save the above code as 'rename-component.ts' // 2. Run from your terminal in the project root: // npx vue-metamorph rename-component.ts --files '**/*.vue'

vue-metamorph --version

Debug

Known issues

breakingVue Metamorph v3.2.3 replaced the underlying AST manipulation libraries `recast` and `ast-types` with their maintained forks, `recast-x` and `ast-types-x`. While intended to be largely compatible, direct reliance on specific internal APIs or subtle behavior differences of the original unmaintained libraries could lead to unexpected issues or require adjustments in existing codemods.

fix

Review existing codemods for direct imports or assumptions about `recast` or `ast-types`. Replace with `recast-x` and `ast-types-x` imports where applicable and test thoroughly. Consult the `recast-x` and `ast-types-x` documentation for any specific migration notes.

affects: >=3.2.3

gotchaVersion 3.2.4 downgraded the Babel parser to an older alpha version (8.0.0-alpha.12) to resolve issues with parsing specific TypeScript syntax, namely `TSInterfaceHeritage` and `TSClassImplements`. This means newer or more advanced TypeScript features relying on later Babel parser updates might not be fully supported or could cause parsing errors until the Babel parser is updated again.

fix

Be aware of potential limitations when processing files with very new or complex TypeScript syntax. Ensure your environment uses the specified Babel parser version if encountering parsing errors for these specific TS constructs, or update `vue-metamorph` to a version that addresses this with a newer parser.

affects: >=3.2.4 <3.3.0

gotchaSince version 3.3.1, the `errorRecovery` parser option has been enabled. While this can allow `vue-metamorph` to parse some files even with minor syntax errors, it may also lead to unexpected AST structures or incomplete transformations if the underlying code is malformed. Codemods might operate on a partially recovered AST, which may not represent the developer's intent.

fix

Ensure source files are syntactically correct before running codemods for predictable results. If unusual transformation outcomes occur, verify the integrity of the source code. The `errorRecovery` option is a fallback, not a substitute for valid syntax.

affects: >=3.3.1

gotchaThe library primarily uses a CLI for execution, taking codemod plugins as arguments. Directly importing and running a defined `Codemod` object within an application requires wrapping it with the internal `vue-metamorph` runner logic, which is not directly exposed as a simple public API.

fix

For running codemods, leverage the provided CLI via `npx vue-metamorph your-codemod.ts --files 'path/to/files/**/*'` as the primary execution mechanism. If programmatic execution is strictly required, investigate the `vue-metamorph` source code for how it invokes codemod plugins, but be aware this is an undocumented and potentially unstable API.

affects: >=3.0.0

breakingVue Metamorph ensures syntactically correct output but does not automatically format the code. The output might lack consistent indentation or follow specific style guides, which can lead to large diffs if not addressed.

fix

Integrate a code formatter like Prettier or ESLint with auto-fix into your codemod workflow. Run the formatter on the affected files immediately after executing `vue-metamorph` to maintain code style and minimize diff noise.

affects: >=3.0.0

Errors

Common errors & fixes

Error: 'TSInterfaceHeritage' is not a valid node type

The underlying Babel parser version is too old or has issues with specific TypeScript syntax like interface heritage clauses.

fix

This issue was specifically addressed by downgrading the Babel parser in `vue-metamorph` v3.2.4. Ensure you are using `vue-metamorph` version 3.2.4 or newer. If the problem persists, check for new updates that might further resolve parser compatibility.

TypeError: node.someProperty is not a function (where node comes from recast or ast-types)

Using an older version of `vue-metamorph` that relied on the unmaintained `recast` or `ast-types` libraries, which may have different APIs or be incompatible with newer JavaScript/TypeScript syntax.

fix

Upgrade `vue-metamorph` to version 3.2.3 or higher. This version replaces `recast` and `ast-types` with their actively maintained forks, `recast-x` and `ast-types-x`, which are more robust with modern syntax.

Error: Unknown node type: VSomeNewVueSyntax

The `vue-eslint-parser` dependency used by `vue-metamorph` is outdated and does not recognize newer Vue template syntax elements.

fix

Update your `vue-metamorph` package to the latest version. Recent releases frequently bump parser dependencies like `vue-eslint-parser` to support newer Vue features and syntax. If the issue persists with the latest version, consider filing an issue with the `vue-metamorph` project.

Upgrade

Version history

3.3.4latest on npm

Audit

Dependencies

vue-eslint-parserrequiredUsed for parsing Vue Single File Component templates and scripts, providing the ASTs for transformation.

@babel/parserrequiredUtilized for parsing JavaScript and TypeScript code within Vue SFCs and standalone files.

postcssrequiredHandles the parsing and manipulation of CSS and various preprocessor styles (SCSS, LESS, SASS, Stylus).

recast-xrequiredProvides the core API for AST traversal and mutation, replacing the unmaintained 'recast' library.

ast-types-xrequiredDefines the AST node types and builder functions, replacing the unmaintained 'ast-types' library and working in conjunction with 'recast-x'.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/UnrefinedBrain/vue-metamorph ↗

packagehttps://www.npmjs.com/package/vue-metamorph ↗