Vue Pug ESLint Plugin

Common errors

• Error: Failed to load plugin 'vue-pug' declared in '...', It was not found.

  cause The `eslint-plugin-vue-pug` package is not installed or incorrectly referenced in the ESLint configuration.
  fix Ensure `eslint-plugin-vue-pug` is installed: `npm install eslint-plugin-vue-pug eslint-plugin-vue --save-dev` or `yarn add -D eslint-plugin-vue-pug eslint-plugin-vue`. Verify the plugin name 'vue-pug' is correctly spelled in your `.eslintrc` plugins array.

• Error: Parsing error: The template requires a parser to be specified.

  cause This error typically indicates that `@vue/eslint-parser` or another template-aware parser is not correctly configured for your `.vue` files, or that it cannot correctly interpret the Pug syntax.
  fix Ensure `eslint-plugin-vue` is correctly configured and its recommended configuration is extended, as it brings in `@vue/eslint-parser`. Also, verify that the Pug templates themselves are well-formed and valid Pug syntax.

• Error: Invalid configuration for rule 'vue-pug/some-rule-name'

  cause The specified rule does not exist, is misspelled, or is not available in the currently loaded version of the plugin.
  fix Double-check the rule name for typos. Refer to the `eslint-plugin-vue-pug` documentation or its `lib/rules` directory on GitHub to confirm available rule names and their options.

Warnings

• breaking Version `0.6.0` removed the `vca-style` configuration option and instead aligned with `vue3-recommended`. Users migrating from older versions that relied on `vca-style` for Vue Composition API linting will need to update their extends configuration.
  Fix: Update your `.eslintrc` configuration to use `plugin:vue/vue3-recommended` (or another appropriate `eslint-plugin-vue` recommended config) and ensure `plugin:vue-pug/recommended` is also listed.
• gotcha This plugin has a peer dependency on `eslint-plugin-vue`. Mismatched versions between the two plugins can lead to unexpected parsing errors, unapplied rules, or complete failure of the linting process.
  Fix: Ensure that your installed version of `eslint-plugin-vue` satisfies the peer dependency range specified by `eslint-plugin-vue-pug`. Typically, running `npm install` or `yarn install` will alert you to peer dependency issues, or explicitly install compatible versions.
• gotcha While `eslint-plugin-vue-pug` adds rules for Pug, it relies on `@vue/eslint-parser` (which is typically part of `eslint-plugin-vue`'s setup) to actually parse the Pug template syntax. Incorrect `parserOptions.parser` configuration for the `<script>` blocks (e.g., missing Babel or TypeScript parser) can prevent ESLint from properly processing Vue SFCs, even if Pug linting rules are defined.
  Fix: Ensure your `.eslintrc` includes an appropriate `parser` in `parserOptions` (e.g., `@babel/eslint-parser` for JavaScript or `@typescript-eslint/parser` for TypeScript) to handle the `<script>` sections of your Vue files, as `@vue/eslint-parser` handles the overall SFC structure and template.

Install

• npm install eslint-plugin-vue-pug npm
• yarn add eslint-plugin-vue-pug yarn
• pnpm add eslint-plugin-vue-pug pnpm

Imports

• Plugin registration
  wrong:

  const vuePugPlugin = require('eslint-plugin-vue-pug'); // This is how ESLint internally loads the plugin, not for user configuration.

  correct:

  {
    "plugins": [
      "vue-pug"
    ]
  }

  ESLint plugins are registered in the `plugins` array of your `.eslintrc` configuration file, making their rules and recommended configs available.
• Recommended configuration
  wrong:

  {
    "extends": [
      "plugin:vue-pug"
    ]
  } // Missing '/recommended' suffix, will not load predefined rules.

  correct:

  {
    "extends": [
      "plugin:vue/vue3-recommended",
      "plugin:vue-pug/recommended"
    ]
  }

  To leverage the recommended rules provided by `eslint-plugin-vue-pug`, extend its configuration after the base `eslint-plugin-vue` recommended config.
• Individual rule
  wrong:

  {
    "rules": {
      "no-bare-template-tag": "error" // Rules must be prefixed with the plugin name.
    }
  }

  correct:

  {
    "rules": {
      "vue-pug/no-bare-template-tag": "error"
    }
  }

  When configuring individual rules, you must prefix them with `vue-pug/` to indicate they belong to this plugin.

Quickstart

Demonstrates how to install and configure `eslint-plugin-vue-pug` in an ESLint configuration file (`.eslintrc.cjs`) for a Vue 3 project using Pug templates. This setup enables basic linting rules for Pug within Vue Single File Components, integrating with the recommended configurations of both `eslint` and `eslint-plugin-vue`.

module.exports = {
  root: true,
  env: {
    node: true,
    browser: true
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended', // Or vue2-recommended, essential, etc.
    'plugin:vue-pug/recommended'  // Integrates Pug-specific linting
  ],
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
    // The parser for <script> blocks in Vue SFCs
    parser: '@babel/eslint-parser', // Or '@typescript-eslint/parser' if using TypeScript
    requireConfigFile: false
  },
  rules: {
    // Example of a specific vue-pug rule
    'vue-pug/no-bare-template-tag': 'error',
    'vue-pug/no-dupe-attributes': 'error',
    'vue-pug/attribute-hyphenation': ['error', 'always'],

    // General ESLint rules
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
  }
};