Step-by-step guide for creating and implementing lint rules in Biome's analyzer. Use when implementing rules like noVar, useConst, or any custom lint/assist rule, adding code actions to fix diagnostics, implementing semantic analysis for binding references, or adding configurable options to rules.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Step-by-step guide for creating and implementing lint rules in Biome's analyzer. Use when implementing rules like noVar, useConst, or any custom lint/assist rule, adding code actions to fix diagnostics, implementing semantic analysis for binding references, or adding configurable options to rules.
compatibility
Designed for coding agents working on the Biome codebase (github.com/biomejs/biome).
Purpose
Use this skill when creating new lint rules or assist actions for Biome. It provides scaffolding commands, implementation patterns, testing workflows, and documentation guidelines.
Prerequisites
Install required tools: just install-tools
Ensure cargo, just, and pnpm are available
Read crates/biome_analyze/CONTRIBUTING.md for in-depth concepts
Common Workflows
Create a New Lint Rule
Generate scaffolding for a JavaScript lint rule:
just new-js-lintrule useMyRuleName
For other languages:
just new-css-lintrule myRuleName
just new-json-lintrule myRuleName
just new-graphql-lintrule myRuleName
This creates a file in crates/biome_<language>_analyze/src/lint/nursery/use_my_rule_name.rs
All new lint rules must be placed in the nursery group, and require a patch changeset. Use the changeset skill to learn more about writing good changesets.
Implement the Rule
Basic rule structure (generated by scaffolding):
use biome_analyze::{context::RuleContext, declare_lint_rule, Rule, RuleDiagnostic};
use biome_js_syntax::JsIdentifierBinding;
use biome_rowan::AstNode;
declare_lint_rule! {
/// Disallows the use of prohibited identifiers.pub UseMyRuleName {
version: "next",
name: "useMyRuleName",
language: "js",
recommended: false,
}
}
implRuleforUseMyRuleName {
typeQuery = Ast<JsIdentifierBinding>;
typeState = ();
typeSignals = Option<Self::State>;
typeOptions = ();
fnrun(ctx: &RuleContext<Self>) ->Self::Signals {
letbinding = ctx.query();
// Check if identifier matches your rule logicif binding.name_token().ok()?.text() == "prohibited_name" {
returnSome(());
}
None
}
fndiagnostic(ctx: &RuleContext<Self>, _state: &Self::State) ->Option<RuleDiagnostic> {
letnode = ctx.query();
Some(
RuleDiagnostic::new(
rule_category!(),
node.range(),
// Pillar 1 — WHAT the error is.
markup! {
"This identifier "<Emphasis>"prohibited_name"</Emphasis>" is not allowed."
},
)
// Pillar 2 — WHY it is triggered / why it is a problem.
.note(markup! {
"Using this identifier leads to [specific problem]."
})
// Pillar 3 — WHAT the user should do to fix it.// Use a code action instead when an automated fix is possible.
.note(markup! {
"Replace it with [alternative] or remove it entirely."
}),
)
}
}
Note: It's critically important to follow the guidelines in the High Quality Diagnostics section below when writing diagnostics.
The Three Diagnostic Pillars (REQUIRED)
Every diagnostic must follow the three pillars defined in crates/biome_analyze/CONTRIBUTING.md:
Pillar
Question answered
Implemented as
1
What is the error?
The RuleDiagnostic message (first argument to markup!)
2
Why is it a problem?
A .note() explaining the consequence or rationale
3
What should the user do?
A code action (action fn), or a second .note() if no fix is available
Example from noUnusedVariables:
RuleDiagnostic::new(
rule_category!(),
range,
// Pillar 1: what
markup! { "This variable "<Emphasis>{name}</Emphasis>" is unused." },
)
// Pillar 2: why
.note(markup! {
"Unused variables are often the result of typos, incomplete refactors, or other sources of bugs."
})
// Pillar 3: what to do (here as a note; ideally a code action)
.note(markup! {
"Remove the variable or use it."
})
Common mistakes to avoid:
Combining pillars 2 and 3 into a single note — keep them separate.
Writing pillar 3 as the only note, skipping pillar 2.
Writing a pillar 1 message that already contains "why" — the message should stay short and factual; move the rationale to pillar 2.
Using Semantic Model
For rules that need binding analysis:
use crate::services::semantic::Semantic;
implRuleforMySemanticRule {
typeQuery = Semantic<JsReferenceIdentifier>;
fnrun(ctx: &RuleContext<Self>) ->Self::Signals {
letnode = ctx.query();
letmodel = ctx.model();
// Check if binding is declaredletbinding = node.binding(model)?;
// Get all references to this bindingletall_refs = binding.all_references(model);
// Get only read referencesletread_refs = binding.all_reads(model);
// Get only write referencesletwrite_refs = binding.all_writes(model);
Some(())
}
}
<!-- should not generate diagnostics --><!doctype html><html>...</html>
For languages that support both comment styles, use /* */ or // as appropriate. The comment should be the very first line of the file.
These magic comments:
Document the intent of the test file
Help reviewers understand what's expected
Serve as a quick reference when debugging test failures
Example invalid.js:
// should generate diagnostics
**Every test file must start with a top-level comment** declaring whether it expects diagnostics. The test runner enforces this — see the `testing-codegen` skill for full rules. The short version:
`valid.js` — comment is **mandatory** (test panics without it):
```js
/* should not generate diagnostics */
const x = 1;
const y = 2;
invalid.js — comment is strongly recommended (also enforced when present):
/* should not generate diagnostics */const allowed_name = 1;
const another_allowed = 2;
Run snapshot tests:
just test-lintrule useMyRuleName
Review snapshots:
cargo insta accept # accept all snapshots
cargo insta reject # reject all snapshots
Generate Analyzer Code
During development, use the lightweight codegen commands:
just gen-rules # Updates rule registrations in *_analyze crates
just gen-configuration # Updates configuration schemas
These generate enough code to compile and test your rule without errors.
For full codegen (migrations, schema, bindings, formatting), run:
just gen-analyzer
Note: The CI autofix job runs gen-analyzer automatically when you open a PR, so running it locally is optional.
Format and Lint
Before committing:
just f # Format code
just l # Lint code
Adding Configurable Options
When a rule needs user-configurable behavior, add options via the biome_rule_options crate.
For the full reference (merge strategies, design guidelines, common patterns), see
references/OPTIONS.md.
Quick workflow:
Step 1. Define the options type in biome_rule_options/src/<snake_case_rule_name>.rs:
Step 3. Test with options.json in the test directory (see references/OPTIONS.md for examples).
Step 4. Document the options in the rule's rustdoc comments, including valid and invalid test cases for each option.
Step 5. Run codegen: just gen-rules && just gen-configuration
Key rules:
All fields must be Option<T> for config merging to work
Use Box<[Box<str>]> instead of Vec<String> for collection fields
Use #[derive(Merge)] for simple cases, implement Merge manually for collections
Only add options when truly needed (conflicting community preferences, multiple valid interpretations)
All options must be documented in the rule's documentation.
Tips
Rule naming: Use no* prefix for rules that forbid something (e.g., noVar), use* for rules that mandate something (e.g., useConst)
Nursery group: All new rules start in the nursery group
Semantic queries: Use Semantic<Node> query when you need binding/scope analysis
Multiple signals: Return Vec<Self::State> or Box<[Self::State]> to emit multiple diagnostics
Safe vs Unsafe fixes: Mark fixes as Unsafe if they could change program behavior
Check for globals: Always verify if a variable is global before reporting it (use semantic model)
Error recovery: When navigating CST, use .ok()? pattern to handle missing nodes gracefully
Testing arrays: Use .jsonc files with arrays of code snippets for multiple test cases
Common Mistakes to Avoid
Generally, mistakes revolve around allocating unnecessary data during rule execution, which can lead to performance issues. Common examples include:
Placing String or Box<str> in a Rule's State type. It's a strong indicator that you are allocating a string unnecessarily. If the string comes from a CST token, this usually can be avoided by using TokenText instead.
Building strings or other data structures only used in the code action in run() instead of action(). run() should only decide whether to emit a diagnostic; action() should build the fix. This matters for performance because building the action can be expensive, and we should avoid doing it when no diagnostic is emitted.
Recursion. It's often completely unnecessary to write recursive functions, especially when you need to traverse node trees. There are existing utilities like ancestors(), descendants(), and preorder() that can cover the vast majority of cases.
Diagnostics must convey, in order: (1) what the problem is, (2) why it is a problem, (3) how to fix it — the fix goes in the action() message when one exists, otherwise in the diagnostic advice. This is the same three-pillar rule shown in the diagnostic example near the top of this skill.
For the full treatment — message vs. advice, code frames, good and bad phrasing examples, severity levels — see the diagnostics-development skill, which is the canonical source. Do not duplicate that guidance here.
Tips
New rules are always in the nursery group. No need to move them to another category.
Changesets are always required for new rules. New rules are patch level changes. There's a skill to help write good changesets.
References
Full guide: crates/biome_analyze/CONTRIBUTING.md
Rule examples: crates/biome_js_analyze/src/lint/
Semantic model: Search for Semantic< in existing rules
Testing guide: Main CONTRIBUTING.md testing section
