add-eslint-rule

name	add-eslint-rule
description	Walks through the full workflow of adding a new ESLint rule to eslint-plugin-svelte — scaffolding via `pnpm run new`, implementing the rule, writing fixture-based tests, updating generated artifacts via `pnpm run update`, and adding a changeset. Use this when the user asks to add, implement, or create a new lint rule in this repository.

Add a new ESLint rule to eslint-plugin-svelte

This skill describes the end-to-end workflow for adding a new rule to eslint-plugin-svelte. It covers the repository's automation scripts so you don't reinvent any of them.

When to use

Use this skill whenever the user asks to:

• Add / implement / create a new lint rule for Svelte code.
• Port an existing rule from another plugin.
• Detect a new pattern in .svelte files and report / autofix it.

Do not use it for fixing or modifying an existing rule (just edit the rule file directly), or for general refactors of plugin internals.

Prerequisites

• Repository root is the monorepo root (eslint-plugin-svelte/).
• All commands below run from packages/eslint-plugin-svelte/ unless noted.
• Node + pnpm install already done.

Step-by-step workflow

1. Confirm the target Svelte version and rule semantics

Before writing any code, pin down:

• What pattern is being reported. Quote the relevant Svelte docs (use the svelte MCP server's get-documentation if available).
• Which Svelte major version(s) the pattern applies to. Rules that only make sense in Svelte 5 (declaration tags, runes, etc.) must be gated with conditions: [{ svelteVersions: ['5'] }]. Rules that only apply pre-5 use ['3/4']. Search existing rules for examples: grep -rn "svelteVersions" packages/eslint-plugin-svelte/src/rules/.
• Whether to autofix or suggest. Autofix only if the transformation is unambiguous and preserves behavior. Otherwise use hasSuggestions: true and provide a suggest array. Look at no-at-debug-tags.ts (suggestion-style) and prefer-derived-over-derived-by.ts (autofix-style) for templates.
• Category. Pick from existing values used in meta.docs.category: 'Best Practices', 'Stylistic Issues', 'Security Vulnerability', 'Possible Errors', 'System', 'Extension Rules', 'SvelteKit'.

2. Scaffold with pnpm run new

From packages/eslint-plugin-svelte/:

pnpm run new <rule-id>

This script (tools/new-rule.ts) creates four artifacts:

• src/rules/<rule-id>.ts — rule skeleton.
• tests/src/rules/<rule-id>.ts — RuleTester runner that loads fixtures.
• docs/rules/<rule-id>.md (at the repo root docs/) — documentation skeleton.
• tests/fixtures/rules/<rule-id>/{valid,invalid}/ — fixture directories.

Never hand-author these — always go through pnpm run new so the scaffolding matches the repository's expected layout.

3. Implement the rule

Edit src/rules/<rule-id>.ts:

• Fill in meta.docs.description, category, recommended.
• Add conditions (see step 1) if the rule is version-sensitive.
• Set type: 'problem' | 'suggestion' | 'layout'.
• Set fixable: 'code' or hasSuggestions: true as appropriate.
• Replace messages: {} with real message IDs.
• Implement create(context) returning visitors. For Svelte-specific AST nodes (e.g. SvelteConstTag, SvelteDeclarationTag, SvelteIfBlock, SvelteMustacheTag), use string visitor keys — they are already typed via src/types-for-node.ts.

Conventions to follow:

• Match existing comment style — generally no JSDoc on the default export; short single-line comments only when intent is non-obvious.
• Use context.sourceCode (not the deprecated context.getSourceCode()).
• Keep fixers minimal: prefer fixer.removeRange / fixer.replaceTextRange with explicit offsets over textual heuristics where possible.

4. Add fixtures

The test runner (tests/utils/utils.ts → loadTestCases) discovers fixtures automatically. Conventions:

• Input files go in tests/fixtures/rules/<rule-id>/{valid,invalid}/ and must end with -input.svelte (or -input.svelte.ts, -input.ts, etc. — anything matching *-input.*).
• For invalid fixtures, -errors.yaml and -output.svelte are generated automatically the first time you run tests. Delete those files and rerun to regenerate when the rule changes.
• To force regeneration of all fixture outputs: pnpm run test:update-fixtures -- -g <rule-id> (or set UPDATE_FIXTURES=1).
• Per-fixture config: drop a JSON file beside the input, named <basename>-config.json (e.g. case01-config.json) for options/parser settings. To apply config to all fixtures in a directory, use _config.json.
• Per-fixture environment requirements: drop <basename>-requirements.json with { "svelte": ">=5.55.9" } etc. Fixtures whose requirements don't match the currently installed deps are skipped silently.
• Use {"only": true} in a config file to focus a single fixture during dev — remove before committing.

Make sure to cover at least:

• A baseline valid case (so the rule has something to not report).
• A baseline invalid case showing the primary message.
• Edge cases relevant to the rule (whitespace, nested blocks, multiple matches per file).

5. Run tests

Always run tests scoped to the rule to keep feedback fast:

pnpm run mocha "tests/src/**/*.ts" --reporter dot --timeout 60000 -- -g <rule-id>

To regenerate fixtures while running:

UPDATE_FIXTURES=1 pnpm run mocha "tests/src/**/*.ts" --reporter dot --timeout 60000 -- -g <rule-id>

Inspect the generated *-errors.yaml and *-output.svelte — they encode the rule's behavior contract. Don't blindly accept them; verify they match intent.

After per-rule tests pass, run the full suite once before committing:

pnpm run test

6. Run pnpm run update

From packages/eslint-plugin-svelte/:

pnpm run update

This sequences eight generators (see tools/update.ts):

• update-rules — regenerates src/utils/rules.ts (the registry array). Required for the test runner to find the new rule via plugin.rules[<rule-id>]. Without this, tests fail with Cannot read properties of undefined (reading 'meta').
• update-rulesets — refreshes config presets (recommended, etc.) based on meta.docs.recommended.
• update-docs — regenerates header blocks in each rule's doc file.
• update-readme — refreshes the rules table in the repo root README.md.
• update-docs-rules-index — refreshes docs/rules.md.
• update-types-for-node — refreshes src/types-for-node.ts (node visitor types).
• update-meta — refreshes src/meta.ts (version metadata).
• update-rule-types — regenerates src/rule-types.ts (typed rule option entries).

If pnpm run update errors partway through (e.g. on a Prettier/PostCSS parse error in some unrelated doc), check git diff to confirm the early generators (which include update-rules) ran. As long as src/utils/rules.ts lists your new rule, the test suite will work; you can run failing generators individually via pnpm run ts ./tools/<generator>.ts.

After update, revert unrelated drift in fixtures or other rules — git checkout -- <path> for any file that was touched but isn't part of your rule. Common drift sources: tests/fixtures/rules/max-lines-per-block/**/*-errors.yaml formatting churn.

7. Lint

pnpm run lint:es src/rules/<rule-id>.ts

Auto-fix with pnpm run lint-fix. The plugin lints itself, so any style violations in your new rule will block CI.

8. Add a changeset

From the repo root:

pnpm exec changeset

…or hand-write .changeset/<slug>.md:

---
'eslint-plugin-svelte': minor
---

feat: add `svelte/<rule-id>` rule

Use minor for new rules, patch for bug fixes / docs-only changes, major for breaking changes. Look at recent merged changesets via git log -- .changeset/*.md for tone.

9. Commit

Stage exactly the files you intend to ship — at minimum:

• .changeset/<slug>.md
• README.md (auto-edited)
• docs/rules.md (auto-edited)
• docs/rules/<rule-id>.md
• packages/eslint-plugin-svelte/src/rule-types.ts (auto-edited)
• packages/eslint-plugin-svelte/src/rules/<rule-id>.ts
• packages/eslint-plugin-svelte/src/utils/rules.ts (auto-edited)
• packages/eslint-plugin-svelte/tests/fixtures/rules/<rule-id>/
• packages/eslint-plugin-svelte/tests/src/rules/<rule-id>.ts

Skip any fixture/doc that wasn't intentionally changed (revert with git checkout).

Quick checklist

• pnpm run new <rule-id> scaffolded.
• Rule implemented in src/rules/<rule-id>.ts with meta, messages, conditions (if version-sensitive), and visitors.
• At least one valid + one invalid fixture.
• pnpm run mocha "tests/src/**/*.ts" -- -g <rule-id> passes.
• Generated *-errors.yaml and *-output.svelte reviewed.
• pnpm run update completed; src/utils/rules.ts lists the rule.
• Full pnpm run test passes.
• pnpm run lint:es clean.
• docs/rules/<rule-id>.md filled in (description, examples, "Further Reading").
• Changeset added with minor bump.
• Unrelated drift reverted from the working tree.

Common pitfalls

• Cannot read properties of undefined (reading 'meta') during tests. You forgot pnpm run update (or at least pnpm run ts ./tools/update-rules.ts). The rule isn't in the registry yet.
• Fixtures silently skipped. A *-requirements.json is excluding the fixture under the current dep versions. Confirm with pnpm list svelte etc.
• Rule fires on the wrong Svelte version. Forgot conditions in meta. Add a svelteVersions array.
• Auto-fix breaks code in edge cases (whitespace, comments). Prefer working with the AST's range and getText plus a precise regex, rather than full-text replacement of the node.
• pnpm run update blew up mid-way. Check git status; the earlier generators usually completed. Don't block the whole rule on an unrelated Prettier error in a doc you didn't touch.
• Prettier formatting error on commit. Run pnpm run lint-fix or check the offending file via the --check output.

Reference: rule anatomy

Smallest viable rule, mirroring the repo's conventions:

import { createRule } from '../utils/index.js';

export default createRule('<rule-id>', {
  meta: {
    docs: {
      description: '...',
      category: 'Best Practices',
      recommended: false
    },
    fixable: 'code',
    schema: [],
    messages: {
      unexpected: '...'
    },
    type: 'suggestion',
    conditions: [
      {
        svelteVersions: ['5']
      }
    ]
  },
  create(context) {
    return {
      SvelteConstTag(node) {
        context.report({
          node,
          messageId: 'unexpected',
          fix(fixer) {
            // minimal, range-based fix
            return null;
          }
        });
      }
    };
  }
});