vue-sfcmod
is a framework for codemodding Vue 3 Single-File Components. It aims to support <script>
codemods for both JavaScript and TypeScript with JSCodeshift, <template>
codemods with the Vue compiler and <style>
codemods with tools to be determined.
This project couldn't exist without the prior work done by vue-codemod. This repository started as a fork of vue-codemod
. The decision to fork was made because:
vue-codemod
appears to be unmaintained since 2021vue-codemod
supports both Vue 2 and Vue 3 whereas this project wants a smaller maintenance surface and only supports Vue 3- This project targets the whole of SFC files, not just JavaScript
vue-codemod
ships and maintains transform scripts, whereas this project aims to provide a raw codemodding framework rather than pre-built codemods
This project also takes inspiration from vue-template-ast-to-template, a Vue 2 template stringifier. vue-sfcmod
was rewritten from scratch to target Vue 3 ASTs, however.
I'm looking for co-maintainers with expertise on the Vue.js compiler. The lack of documentation on the compiler prevents me from fully implementing an API and stringifier for Vue codemodding. I have to reverse engineer the AST and figure out what's expected, and I run into occasional limitations that I believe are due to the compiler not being written with codemodding in mind.
I need help from someone with expertise in Vue.js internals and with the ability to push for change within the Vue compiler ecosystem if needed. There are limitations to what vue-sfcmod can do (described below in this README) that I can't work around without changes to the compiler to directly support rewriting an AST into source code. I am also stuck with codegen nodes, as part of their execution context is handled implicitly and they can't be passed to a JS codemodding engine as is without reconstructing the context (which I don't know how to do since the context isn't documented).
I can't justify the time it takes me to reverse engineer the AST to improve coverage, so I'm unlikely to keep improving the Vue API on my own. However, I remain committed to improving the CLI to support both codemodding and static analysis needs.
yarn add -D vue-sfcmod
To transform files, type the following command:
yarn vue-sfcmod <path> -t <transformation>
path
(required) - files or directory to transformtransformation
- path to a module exporting a transformation function (JS/TS only) or an object with transformation functions:script
key for<script>
,<script setup>
and JS/TS filestemplate
for HTML<template>
style
for CSS and<style>
(not yet implemented)
yarn vue-sfcmod <path>
The -t transformation
parameter is optional. If unset, vue-sfcmod
will launch an interactive prompt to let users select a preset transformation to run. To configure presets, create a configuration file as explained in the next section.
yarn vue-sfcmod <path 1> <path 2> <path 3> -t <transformation>
You may pass as many paths as you like. Each is resolved using globby.
yarn vue-sfcmod <path> -t <transformation> --custom-flag --foo=value --bar value
You may pass custom CLI parameters that will be passed to transformation functions. Three syntaxes are supported:
--custom-flag
without a value is mapped to{ customFlag: true }
--foo=value
is mapped to{ foo: value }
--bar value
is mapped to{ bar: value }
Custom parameter names are converted to Pascal case in the object received by transformation functions. Check out the params
example for a fully working example.
vue-sfcmod --version
prints the current versionvue-sfcmod --help
prints usage documentation
--custom-opt [custom value, else customOpt will be true] [...add as many custom opts as wanted]`
Any CLI option you pass apart from --version
, --help
and -t
will be passed to the script, style and template transformation functions in an object. For instance, if you pass --classes-to-add="foo bar"
, you'll receive { classesToAdd: 'foo bar' }
as a third argument to your transformation functions.
To pass configuration options to vue-sfcmod
, create a sfcmod.config.ts
file at the root of your project. Below is a sample configuration file. You can also check out the full sample file.
import type { SfcmodConfig } from 'vue-sfcmod'
const config: SfcmodConfig = {
// ...
}
export default config
This project uses cosmiconfig to read configuration files. Check the documentation for a full list of supported syntaxes and file names. TypeScript usage is recommended to get IDE autocompletion and type checking.
Array of paths to preset transformation files, that are proposed to end users in an interactive prompt when they don't pass a -t
flag to the CLI.
string | { glob: string, name: (string) => string }
Each item in the array can either be a glob (resolved with globby), or an object with a glob
property and a name
property. The name
property is a function called for each file matched by the glob. It receives the path as an input, and outputs a name used in the interactive prompt.
presets: [
{
// In this example, we use folder names as a name in the CLI.
glob: './examples/**/transformation.cjs',
name: (filePath: string) =>
filePath
.replace(/\/transformation.cjs$/, '')
.split('/')
.slice(-1)[0],
},
],
To use vue-sfcmod
programmatically, you may import the runTransformation
function. It runs a transformation on a single file.
function runTransformation(
fileInfo: {
path: string
source: string
},
transformationModule: TransformationModule,
options?: { [key: string]: unknown },
): string
fileInfo
is the file to transformfileInfo.path
is used to distinguish Vue files from JS/TS filesfileInfo.source
is the content of the file
transformationModule
is the file containing the transformation to apply (matching the signature of the-t
CLI option)options
is an arbitrary object of options passed to the transformation functions; it is optional
The function returns a string
, containing the transformed content.
Elements using the v-text
directive and children are not supported. The Vue compiler does not compile children of elements that use the v-text
directive, so we cannot provide the content of children.
Content inside v-html
directives is printed as is and cannot be transformed.
The built-in Vue transition
component is returned by the Vue compiler without HTML comment children. Because the children are missing from the compiler AST, they cannot be recovered by vue-sfcmod. Upstream issue.
When strings are passed to style
attributes, it is converted to JSON (and deduplicated in the process). This is done by the Vue compiler, and attempting to undo that conversion could result in bugs in the template codemod engine.
- Support applying
jscodeshift
codemods to.vue
files - Support for TypeScript
- Support
<script setup>
- Support
<template>
#15 - Support passing parameters to template transformations
- ongoing - Add an API to search for, edit, remove and inject nodes in template ASTs
- Allow interpreting and modding JS expressions inside
<template>
- Support
<style>
#16 - Support passing parameters to style transformations
- Support :global, :slotted, etc
- Support PostCSS and SCSS style tags
- Basic testing setup and a dummy CLI
- Branch test coverage above 80%
- Add working examples
- Add semantic-release
See https://github.com/facebook/jscodeshift#transform-module
No API yet. You may manually modify the AST provided by the Vue SFC compiler.
Running transformations will generally ruin the formatting of your files. A recommended way to solve that problem is by using Prettier or eslint --fix
.