ESLint Processor for Vue Blocks

2.0.0 · active · verified Sun Apr 19

eslint-processor-vue-blocks enables ESLint to process individual blocks within Vue Single File Components (SFCs) by creating virtual files for each block (e.g., `<style>`, `<custom-block>`). This allows for more granular linting, applying different ESLint configurations and rules to specific parts of a Vue component. The current stable version is 2.0.0, which introduced breaking changes by requiring ESLint v9+ and becoming an ESM-only package. The package is maintained by Antfu and sees updates driven by ecosystem changes like new ESLint versions or Vue SFC parsing improvements. Its key differentiator is providing a flexible way to extend `eslint-plugin-vue`'s default processing, enabling linting of styles or custom blocks independently, which `eslint-plugin-vue` typically delegates or ignores.

Common errors

```
Error: Cannot find module 'eslint-processor-vue-blocks'
```
cause Attempting to `require()` an ESM-only package in a CommonJS context.

fix Ensure your ESLint configuration file (`eslint.config.js`) is treated as an ES Module. This typically means adding `"type": "module"` to your `package.json` or renaming the config file to `.mjs`.
```
TypeError: processorVueBlocks is not a function
```
cause Incorrect import of `processorVueBlocks` or attempt to use it without `import` in an ESM context.

fix Verify that you are using `import processorVueBlocks from 'eslint-processor-vue-blocks'` and that your environment supports ES Modules.
```
ESLint couldn't find the plugin "vue".
```
cause `eslint-plugin-vue` is not installed or correctly configured.

fix Install `eslint-plugin-vue` (e.g., `npm i -D eslint-plugin-vue`) and ensure it is included in your ESLint flat config under the `plugins` key.

Warnings

breaking Version 2.0.0 of `eslint-processor-vue-blocks` requires ESLint v9.0.0 or higher. Older ESLint versions are not supported.
Fix: Upgrade ESLint to version 9.x or later. Ensure your project dependencies reflect `"eslint": "^9.0.0"`.
breaking Since v2.0.0, `eslint-processor-vue-blocks` is an ESM-only package. It no longer provides CommonJS builds.
Fix: If you are using CommonJS, you must switch your ESLint configuration (e.g., `eslint.config.js`) to use ESM syntax (`import`/`export`) or use a tool like `esm-hook` to enable ESM in your CJS environment. Ensure your `package.json` specifies `"type": "module"` if your config is in a `.js` file.
gotcha By default, `eslint-plugin-vue` already handles `<script>` and `<template>` blocks. Enabling them in `eslint-processor-vue-blocks` can lead to duplicate linting or unexpected behavior.
Fix: It is generally recommended to set `script: false` and `template: false` in the `blocks` option of `processorVueBlocks` to avoid conflicts with `eslint-plugin-vue`'s built-in processing.
gotcha This package requires `@vue/compiler-sfc` as a peer dependency for parsing Vue SFCs. Without it, the processor cannot function.
Fix: Ensure `@vue/compiler-sfc` is installed in your project. Add `npm i -D @vue/compiler-sfc` or `yarn add -D @vue/compiler-sfc`.

Install

npm install eslint-processor-vue-blocks npm
yarn add eslint-processor-vue-blocks yarn
pnpm add eslint-processor-vue-blocks pnpm

Imports

processorVueBlocks

wrong:

const processorVueBlocks = require('eslint-processor-vue-blocks')

correct:

import processorVueBlocks from 'eslint-processor-vue-blocks'

ESM-only since v2.0.0. Use this as a function to configure block processing.

mergeProcessors
wrong:
```
import mergeProcessors from 'eslint-merge-processors'
```
correct:
```
import { mergeProcessors } from 'eslint-merge-processors'
```
Named export from `eslint-merge-processors`, commonly used to combine multiple processors.
ConfigObject
```
import type { Linter } from 'eslint'
```
While not directly from this package, typings for ESLint configuration are crucial for `eslint.config.js`.

Quickstart

This quickstart demonstrates how to configure `eslint-processor-vue-blocks` with ESLint flat config to lint Vue SFC `<style>` and custom blocks alongside `eslint-plugin-vue`.

import { mergeProcessors } from 'eslint-merge-processors'
import pluginVue from 'eslint-plugin-vue'
import processorVueBlocks from 'eslint-processor-vue-blocks'

export default [
  {
    files: ['**/*.vue'],
    plugins: {
      vue: pluginVue,
    },
    processor: mergeProcessors([
      pluginVue.processors['.vue'],
      processorVueBlocks({
        blocks: {
          styles: true,
          customBlocks: true,
          // Usually it's not recommended to lint <script> and <template>
          // As eslint-plugin-vue already provides the support
          script: false,
          template: false,
        }
      }),
    ]),
    rules: {
      // Your Vue-specific rules for script and template
      'vue/no-unused-vars': 'error',
      'vue/multi-word-component-names': 'off'
    }
  },
  {
    files: ['**/*.css', '**/*.vue/*.css'], // Lint CSS files and <style> blocks
    rules: {
      'selector-list-comma-newline-after': 'always',
      // ... your CSS rules
    }
  },
  {
    files: ['**/*.md', '**/*.vue/*.md'], // Example for custom blocks, e.g., <docs lang="md"> 
    rules: {
      'prettier/prettier': 'error' // Assuming you have eslint-plugin-prettier configured
    }
  }
]

view raw JSON →