HTML-Validate Vue.js Plugin

Common errors

• Error: Cannot find module 'html-validate' from '.../node_modules/html-validate-vue'

  cause The peer dependency `html-validate` is not installed or cannot be resolved by the system.
  fix Run `npm install html-validate` or `yarn add html-validate` in your project.

• Error: No transform found for "src/MyComponent.vue" (tried: ...)

  cause The `transform` configuration in `.htmlvalidate.json` does not match the file path, preventing the Vue transformer from being applied.
  fix Verify 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'

  cause The `vue/required-slots` rule detected that a required slot (`body` in this case) was not provided when using a component.
  fix Add 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

  cause Occurs when `html-validate` v9+ is used in a CommonJS project, attempting to import a directory as a plugin instead of an explicit file.
  fix Explicitly 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`.

Warnings

• breaking html-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.
  Fix: Upgrade your Node.js environment to version 20 or newer. Check `engines` field in `package.json` for specific requirements.
• breaking When 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.
  Fix: If 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.
• gotcha Incorrect 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`).
  Fix: Ensure 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.
• gotcha html-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.
  Fix: Ensure `html-validate` is installed as a `devDependency` or `dependency` and its version meets the peer dependency requirements of `html-validate-vue`.
• gotcha Defining 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.
  Fix: Follow the `${component}#${slot}` pattern for keys when defining metadata for component slots in your `elements.json` or inline configuration.

Install

• npm install html-validate-vue npm
• yarn add html-validate-vue yarn
• pnpm add html-validate-vue pnpm

Imports

• 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`.

Quickstart

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>
*/