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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
html-validate-vue
✓ {
"plugins": ["html-validate-vue"],
"transform": {
"^.*\\.vue$": "html-validate-vue"
}
}
The plugin is loaded via configuration strings in .htmlvalidate.json (or similar config files) rather than direct JavaScript `import` statements by end-users. The package registers itself and its transforms with the html-validate core.
html-validate-vue:sfc
✓ {
"transform": {
"^.*\\.vue$": "html-validate-vue:sfc"
}
}
Explicitly specifies the Single File Component (SFC) transformer. Useful when `html-validate-vue:auto` might misinterpret a file or when precise control over the transform is needed. Other named transforms include `:auto`, `:js`, and `:html`.
html-validate-vue:recommended
✓ {
"extends": ["html-validate:recommended", "html-validate-vue:recommended"]
}
Extends the recommended configuration for Vue.js specific rules and element metadata provided by the plugin. This is added to the `extends` array in `.htmlvalidate.json`.
Demonstrates the installation of `html-validate` and `html-validate-vue`, and the essential `.htmlvalidate.json` configuration to enable Vue SFC validation in a project.
npm install --save-dev html-validate html-validate-vue
// .htmlvalidate.json
// Place this file in your project root.
{
"plugins": ["html-validate-vue"],
"extends": [
"html-validate:recommended",
"html-validate-vue:recommended"
],
"elements": ["html5"],
"transform": {
"^.*\\.vue$": "html-validate-vue"
}
}
// Example Vue Single File Component (src/MyComponent.vue)
// This component would be validated by html-validate-vue
// (No actual JavaScript execution here, just demonstrating setup)
/*
<template>
<section>
<h1>Welcome</h1>
<my-button>
<template #default>
Click me
</template>
</my-button>
</section>
</template>
<script>
import MyButton from './MyButton.vue';
export default {
components: { MyButton },
};
</script>
<style scoped>
/* Your styles here */
</style>
*/
html-validate --version
Debug
Known issues
breakinghtml-validate-vue v8.x, aligning with its peer dependency html-validate v8.x, requires Node.js v20 or later. Running on older Node.js versions will result in installation or runtime failures.fixUpgrade your Node.js environment to version 20 or newer. Check `engines` field in `package.json` for specific requirements.
affects: >=8.0.0
breakingWhen upgrading the peer dependency `html-validate` to v9 or later, projects using CommonJS (CJS) might encounter `ERR_UNSUPPORTED_DIR_IMPORT` errors. `html-validate` v9 defaults to ESM, requiring explicit file extensions for local plugin paths in configuration files.fixIf referencing local plugins or configurations in CJS, explicitly add `.js` or `.cjs` extensions. For example, change `"plugins": ["./my-plugin"]` to `"plugins": ["./my-plugin/index.js"]`. Consider migrating to ESM if feasible.
affects: html-validate@>=9.0.0
gotchaIncorrect configuration of the `transform` property in `.htmlvalidate.json` can lead to Vue templates not being validated or being parsed incorrectly. The plugin offers specific named transformers (`html-validate-vue:auto`, `:js`, `:html`, `:sfc`).fixEnsure the `transform` regex matches your Vue files (e.g., `^.*\\.vue$`) and consider explicitly specifying a named transform like `"html-validate-vue:sfc"` if the `auto` detection is insufficient.
affects: >=1.0.0
gotchahtml-validate-vue has a peer dependency on `html-validate`. If `html-validate` is not installed or its version is outside the supported range (`^8.21.0 || ^9.0.0 || ^10.0.0`), the plugin will fail to load or operate correctly.fixEnsure `html-validate` is installed as a `devDependency` or `dependency` and its version meets the peer dependency requirements of `html-validate-vue`.
affects: >=1.0.0
gotchaDefining custom element metadata for specific component slots requires a precise `component#slot` syntax (e.g., `my-component#heading`). Deviating from this delimiter will prevent slot-specific rules from being applied.fixFollow the `${component}#${slot}` pattern for keys when defining metadata for component slots in your `elements.json` or inline configuration. affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'html-validate' from '.../node_modules/html-validate-vue'
The peer dependency `html-validate` is not installed or cannot be resolved by the system.
fixRun `npm install html-validate` or `yarn add html-validate` in your project.
Error: No transform found for "src/MyComponent.vue" (tried: ...)
The `transform` configuration in `.htmlvalidate.json` does not match the file path, preventing the Vue transformer from being applied.
fixVerify the regular expression in your `transform` configuration (e.g., `"^.*\\.vue$": "html-validate-vue"`) or explicitly use a named transform like `"html-validate-vue:sfc"`.
Element <my-component> is missing required slot 'body'
The `vue/required-slots` rule detected that a required slot (`body` in this case) was not provided when using a component.
fixAdd the missing required slot to your component usage, e.g., `<my-component><template #body>...</template></my-component>`.
Error [ERR_UNSUPPORTED_DIR_IMPORT]: Directory import '.../my-local-plugin' is not supported resolving ES modules
Occurs when `html-validate` v9+ is used in a CommonJS project, attempting to import a directory as a plugin instead of an explicit file.
fixExplicitly reference the entry file for local plugins, e.g., change `"plugins": ["./my-local-plugin"]` to `"plugins": ["./my-local-plugin/index.js"]` in your `.htmlvalidate.json`.
Audit
Dependencies
html-validaterequiredCore HTML validation engine; html-validate-vue extends its functionality.