eslint-plugin-harlanzw

eslint-plugin-harlanzw

Harlan's ESLint rules for Vue projects with focus on link hygiene, Nuxt best practices, and Vue reactivity patterns.

Playground

Try the rules in action with a Nuxt ESLint interactive playground:

Rules

Note: These rules are experimental and may change. They will be submitted to the official Vue ESLint plugin for consideration.

The rules are organized into the following categories:

• Link Rules: Ensure link URLs are clean, accessible, and SEO-friendly
• Nuxt Rules: Best practices for Nuxt applications
• Vue Rules: Vue composition API and reactivity best practices
• AI Deslop Rules: Clean AI-generated slop from content markdown
• Prompt Rules: Lint agent prompt files for dangling paths, dilution, and structure
• Docs Rules: Enforce the root-docs contract across a repository's documentation

The plugin also includes 21 prompt linting rules for .prompt.md and .skill.md files. See the prompt configs section below.

Installation

Install the plugin:

pnpm add -D eslint-plugin-harlanzw

Usage

// eslint.config.js
import { harlanzw } from 'eslint-plugin-harlanzw'

export default harlanzw({
  link: true,
  nuxt: true,
  vue: true,
})

The Nuxt and Vue presets cover .vue, .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts files.

Link Options

All link rules share ignoreExternal and exclude options. Configure them once:

export default harlanzw({
  link: {
    ignoreExternal: true, // skip http(s):// URLs and elements with `external` attr
    exclude: ['^/api/', '/OAuth/'], // skip URLs matching any regex pattern
    requireTrailingSlash: true, // passed to link-trailing-slash
  },
  nuxt: true,
  vue: true,
})

Test Rules

Nuxt and Vue presets enable test rules automatically. no-test-file-reads warns when tests read source files or files with unknown paths. Known non-source paths, such as generated .json, .md, and .txt files, are allowed.

Enable test rules alone with tests: true. Disable them with tests: false.

Shared Base

base carries the override blocks that were copy-pasted into every repo: the shared ignore set, node globals, and relaxations for test files, markdown code fences, and example manifests. It is opt in.

import antfu from '@antfu/eslint-config'
import { harlanzw } from 'eslint-plugin-harlanzw'

export default antfu(
  { type: 'lib' },
  ...harlanzw({
    base: true, // or { type: 'app', ignores: ['docs/**'] }
    nuxt: true,
    vue: true,
  }),
)

type defaults to 'lib', which also turns off ts/explicit-function-return-type. ignores appends to the shared set. Every shared ignore glob is recursive, so nested playgrounds and fixtures in a monorepo are covered.

Pass ignores: false to drop the shared ignore block and declare your own. A global ignore cannot be undone by a later config, so this is the only way to keep linting something the shared set covers, such as a playground you lint on purpose. The rule blocks still apply.

agentFiles decides what happens to the prompts you wrote: CLAUDE.md, AGENTS.md, and .cursor. It defaults to 'ignore', keeping them out of the lint run. A global ignore beats any files-scoped config, so harlanzw() switches it to 'lint' whenever its prompt config is enabled, otherwise the prompt rules would never see those files. Set it explicitly to override that.

The .claude directory is always ignored, whatever agentFiles says. Nothing in it is a prompt this repo wrote: its skills are upstream package docs installed by skilld, its context is generated notes and job state, and agents drop whole repo checkouts in there. It also sits in its own block, so ignores: false does not hand it back.

Every rule in these blocks is set to off, and flat config ignores an off entry for a rule whose plugin is absent. So the blocks are safe with any preset, and need no dependency on @antfu/eslint-config.

Spread them without the rule presets when you only want the shared overrides:

import { base } from 'eslint-plugin-harlanzw'

export default antfu({ type: 'lib' }, ...base())

The base blocks come first in the returned array, so put harlanzw() after the preset whose rules it relaxes.

Contents:

Extra Configs

Pass additional flat configs as extra arguments:

export default harlanzw(
  { link: true, nuxt: true, vue: true },
  {
    rules: {
      'harlanzw/link-lowercase': ['error', { ignoreExternal: true }],
    },
  },
)

With @antfu/eslint-config

import antfu from '@antfu/eslint-config'
import { harlanzw } from 'eslint-plugin-harlanzw'

export default antfu(
  { vue: true },
  ...harlanzw({ link: true, nuxt: true, vue: true }),
)

With Nuxt ESLint

import { harlanzw } from 'eslint-plugin-harlanzw'
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  ...harlanzw({ link: true, nuxt: true, vue: true }),
)

Nuxt UI Design Rules

Enable our design rules through your site's existing Nuxt ESLint config:

import { harlanzw } from 'eslint-plugin-harlanzw'
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  ...harlanzw({ nuxt: true, vue: true, nuxtUi: true }),
)

nuxtUi enables automatically when the current package declares @nuxt/ui in dependencies or devDependencies. Use nuxtUi: false to disable it. Use nuxtUi: true when another workspace package owns the dependency. It adds two Vue template checks:

• Warn when Nuxt UI controls or configured wrappers override component appearance.
• Report partial Tailwind class construction in :class and :ui bindings.

Messages guide agents toward component props and shared styling. The rules never change appearance automatically. No runtime Nuxt module or shadcn dependency is needed.

Pass an object to configure component names, allowed classes, slots, sizes, and repair messages. See site configuration for a complete example and coverage limits. Size and variant guidance comes from these explicit options. App configuration is not executed or automatically discovered.

Theme-aware checks

Load the site's CSS to validate utility names, colors, and spacing:

import { tailwind } from 'eslint-plugin-harlanzw/tailwind'

export default withNuxt(
  ...harlanzw(),
  await tailwind({ stylesheet: './app/assets/css/main.css' }),
)

Install @tailwindcss/node@~4.3.3 for this optional helper. It uses your CSS imports, theme tokens, and component styles.

• Valid classes: compiler-backed checks, custom hooks, and layer styles.
• Theme tokens: known token equivalents and optional color and spacing policies.
• Component props: size, color, variant, and configured wrapper values.

OG-image templates are excluded from theme checks by default because their renderer has separate styling rules.

Public API

The factory exposes the raw plugin and framework detection. The package also exports typed rule maps for custom configs.

import type { RuleOptions, Rules } from 'eslint-plugin-harlanzw'
import { harlanzw, plugin } from 'eslint-plugin-harlanzw'

const detected = harlanzw.detectFramework()
const rawPlugin = harlanzw.plugin
const linkOptions: RuleOptions['link-lowercase'] = [{ ignoreExternal: true }]
const linkRule: Rules['link-lowercase'] = ['warn', ...linkOptions]

export default [
  ...plugin.configs.recommended,
  { rules: { 'harlanzw/link-lowercase': linkRule } },
]

You can also select individual presets:

import { plugin } from 'eslint-plugin-harlanzw'

export default [
  ...plugin.configs.link,
  ...plugin.configs.nuxt,
  ...plugin.configs.vue,
  ...plugin.configs.tests,
]

AI Deslop Rules

15 rules for cleaning AI-generated slop from your content markdown files (content/**/*.md). Most rules are auto-fixable. Prose checks skip fenced code blocks opened with backticks or tildes, including fences longer than three characters.

// eslint.config.js
export default harlanzw({
  content: true,
})

Or use the raw config:

import { plugin } from 'eslint-plugin-harlanzw'

export default [
  ...plugin.configs.content,
]

Prompt Rules

21 rules for linting .prompt.md and .skill.md files using a custom prompt language:

import { plugin } from 'eslint-plugin-harlanzw'

export default [
  ...plugin.configs['prompt:recommended'],
  // or stricter:
  // ...plugin.configs['prompt:strict'],
  // for skill files:
  // ...plugin.configs['prompt:skill'],
]

pnpm Rules

Enforces required fields in pnpm-workspace.yaml. Auto-enabled when the file exists.

export default harlanzw({
  pnpm: true,
})

Or use the raw config:

import { plugin } from 'eslint-plugin-harlanzw'

export default [
  ...plugin.configs.pnpm,
]

Docs Rules

Opt-in rules for the root-docs contract: an allowlist for Markdown at the repository root and a lifecycle for docs/. Enable them per repository, since the contract is a convention rather than a fact about Markdown.

import { plugin } from 'eslint-plugin-harlanzw'

export default [
  ...plugin.configs.docs,
]

This config is opinionated and opt-in. It encodes one convention about where Markdown lives and what a brief must say. Nothing in it is enabled by recommended, content, or any prompt:* config, and a test pins that. Every default below is an option, because a repository adopting the config will not share every opinion in it.

docs-root-allowlist and prompt-dangling-path apply to root *.md files only. docs-work-brief-contract and docs-reference-no-status apply to docs/**/*.md. docs-retired-pointer applies to both root *.md and docs/**/*.md:

The defaults are Harlan's. **Next move:** accepts Harlan, Blocked or Ready, and a bucket named after a person is the clearest sign to set your own:

export default [
  {
    rules: {
      'harlanzw/docs-work-brief-contract': ['error', {
        dir: 'docs/initiatives',
        buckets: ['Waiting', 'Go'],
        require: ['title', 'doneMeans'],
      }],
    },
  },
]

Sponsors

Credits

This plugin is based on eslint-plugin-antfu by Anthony Fu.

License

Licensed under the MIT license.

Automatic detection skips known Nuxt UI versions below v4. Explicit nuxtUi configuration overrides detection.