Skip to content

SomtoUgeh/somto-dev-toolkit / skills/biome-gritql

biome-gritql

Verified

Creates and manages Biome GritQL custom lint rules to enforce coding patterns. Use when creating linter rules, enforcing code conventions, preventing anti-patterns, or when the user mentions Biome, GritQL, custom lint rules, or AST-based linting.

Biome GritQL Custom Lint Rules

Create AST-based custom lint rules using Biome's GritQL plugin system.

Quick Start

Create a rule file (rules/no-use-effect-fetch.grit):

`useEffect($callback, $deps)` where {
    $callback <: contains `fetch`,
    register_diagnostic(
        span = $callback,
        message = "Don't fetch inside useEffect. Use TanStack Query instead.",
        severity = "error"
    )
}

Add to biome.json:

{
  "plugins": ["./rules/no-use-effect-fetch.grit"]
}

Run: bunx biome check or any equivalent command to run linter in the codebase

GritQL Syntax

Basic Pattern Matching

`pattern_to_match` where {
    register_diagnostic(
        span = $matched_var,
        message = "Your message here",
        severity = "error"  // hint | info | warn | error
    )
}

make sure to read documentation

Variables

  • $name - captures any single node
  • $args - captures arguments
  • $_ - wildcard (match but don't capture)

Operators

OperatorMeaning
<:matches / contains
<: containsdeep contains
<: r"regex"regex match
notnegation
andboth conditions
oreither condition

Common Rule Patterns

Ban a Function Call

`console.log($args)` where {
    register_diagnostic(
        span = $args,
        message = "Remove console.log before committing",
        severity = "warn"
    )
}

Ban a Hook (React)

`useMemo($args)` where {
    register_diagnostic(
        span = $args,
        message = "useMemo unnecessary with React Compiler. Remove it.",
        severity = "warn"
    )
}

Ban Dynamic Imports

`await import($path)` where {
    register_diagnostic(
        span = $path,
        message = "Use static imports at the top of the file",
        severity = "error"
    )
}

Require Pattern in Context

`useState($initial)` where {
    not $initial <: contains `atom`,
    register_diagnostic(
        span = $initial,
        message = "Prefer Jotai atoms over useState for shared state",
        severity = "info"
    )
}

CSS Rules

language css;

`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Use .color-* utility classes instead of explicit colors"
    )
}

Project Structure

project/
├── biome.json
└── rules/
    ├── no-console-log.grit
    ├── no-use-memo.grit
    ├── no-use-callback.grit
    ├── no-dynamic-import.grit
    └── no-fetch-in-effect.grit

biome.json Configuration

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "plugins": [
    "./rules/no-console-log.grit",
    "./rules/no-use-memo.grit",
    "./rules/no-use-callback.grit"
  ],
  "linter": {
    "enabled": true
  }
}

Creating Rules Workflow

  1. Identify the pattern to ban/enforce
  2. Create .grit file in rules/ directory
  3. Write the GritQL pattern with clear error message
  4. Add path to biome.json plugins array
  5. Test with bunx biome check or any equivalent command to run linter in the codebase

Guidelines

  • Keep error messages actionable - tell the user what to do instead
  • Use severity = "error" for hard requirements, "warn" for preferences
  • Put all .grit files in a rules/ directory
  • Name files descriptively: no-X.grit or prefer-Y.grit
  • Test rules against real code before committing

Why This Matters

Instructions in CLAUDE.md degrade as context fills up. Linter rules provide immediate, persistent feedback. When Claude violates a pattern, it sees the error and self-corrects - no context drift.

Resources

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall