Svelte Rules for AST-Grep

A collection of AST-Grep rules for linting and analyzing Svelte code, with a focus on Svelte 5 best practices and migration patterns.

Overview

This repository contains custom AST-Grep rules specifically designed for Svelte applications. These rules help developers:

• Identify legacy patterns that should be updated for Svelte 5
• Enforce best practices and coding standards
• Facilitate large-scale refactoring efforts
• Maintain code quality across Svelte projects

Getting Started

Prerequisites

• AST-Grep installed
• Node.js and npm for building the Svelte parser

Parser Setup

The rules in this repository require a custom Svelte parser. To set it up:

# Clone the Svelte tree-sitter grammar
git clone https://github.com/tree-sitter-grammars/tree-sitter-svelte
cd tree-sitter-svelte

# Install dependencies
npm install

# Build the parser (adjust extension based on your OS)
# Linux:
npx tree-sitter build -o ../parsers/svelte.so
# macOS:
# npx tree-sitter build -o ../parsers/svelte.dylib
# Windows:
# npx tree-sitter build -o ../parsers/svelte.dll

Note: This relies on the tree-sitter CLI. Installing tree-sitter-cli or using npx is the intended path.

Configuration

To use these rules with the custom Svelte parser, create an sgconfig.yml file in your project root:

ruleDirs: [rules]

customLanguages:
  svelte:
    libraryPath: ./parsers/svelte.so  # Adjust path as needed
    extensions: [svelte]

languageInjections:
  - hostLanguage: svelte
    rule:
      pattern: <script$A>$CODE</script>
    injected: ts

This configuration:

• Discovers rules in the rules/ directory
• Loads the custom Svelte parser
• Parses TypeScript code in <script lang="ts"> blocks as TypeScript

Available Rules

Svelte 5 Migration Rules

These rules help identify patterns that should be updated for Svelte 5:

• avoid-export-let: Recommends using $props() instead of export let for typed props
• avoid-store-auto-sub: Identifies automatic store subscriptions that should use runes
• avoid-create-event-dispatcher: Suggests alternatives to createEventDispatcher
• avoid-reactive-label: Recommends $state() over reactive labels ($:)
• avoid-on-directives: Points out traditional event directives that should use runes

Svelte Legacy Patterns

• svelte-legacy-component: Identifies legacy component usage patterns
• svelte-legacy-lifecycle: Points out deprecated lifecycle methods
• svelte-legacy-slots: Highlights legacy slot usage

Svelte Control Flow

• svelte-if-block: Identifies Svelte {#if} blocks
• svelte-else-if: Identifies Svelte {:else if} blocks
• svelte-else: Identifies Svelte {:else} blocks
• svelte-each: Identifies Svelte {#each} blocks
• svelte-each-with-index: Identifies {#each} blocks with index variables
• svelte-each-keyed: Identifies keyed {#each} blocks
• svelte-await-then: Identifies {#await} blocks with {:then} handlers
• svelte-await-catch: Identifies {#await} blocks with {:catch} handlers

Usage

Running Rules

To run these rules against your Svelte codebase:

# All configured rules (uses sgconfig.yml)
ast-grep scan

# One rule file, whole repo
ast-grep scan --rule rules/avoid-export-let.yml .

# One rule file, a directory
ast-grep scan --rule rules/avoid-export-let.yml src/

# Ad-hoc pattern (no rule file)
ast-grep run --lang svelte -p '{#if $COND}' src

Inline One-off Rules

For quick checks without creating rule files:

# Find all {#if} blocks
ast-grep scan --inline-rules '
id: find-if-blocks
language: svelte
rule:
  pattern: "{#if $COND}"
' src

Quality Checks in TypeScript

For checking code in <script lang="ts"> blocks:

# console.log
ast-grep scan --inline-rules '
id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$)
' src

# any type (broad)
ast-grep scan --inline-rules '
id: no-any
language: TypeScript
rule:
  regex: "\\b:any\\b"
' src

Integration Examples

Svelte 5 Migration Workflow

# Scan for all legacy patterns (requires sgconfig.yml)
ast-grep scan

# Focus on specific legacy patterns
ast-grep scan --rule rules/avoid-reactive-label.yml src          # Find $: reactive labels
ast-grep scan --rule rules/avoid-export-let.yml src              # Find export let statements
ast-grep scan --rule rules/avoid-on-directives.yml src           # Find on: directives
ast-grep scan --rule rules/avoid-create-event-dispatcher.yml src # Find createEventDispatcher usage
ast-grep scan --rule rules/avoid-store-auto-sub.yml src          # Find $store auto-subscriptions

Contributing

Contributions are welcome! Feel free to:

1. Add new rules for Svelte best practices
2. Improve existing rules
3. Add documentation and examples
4. Report issues or suggest improvements

Creating New Rules

1. Create a new .yml file in the rules/ directory
2. Follow the AST-Grep rule format:

   id: rule-identifier
   message: "Description of the issue"
   severity: warning|error|info|hint
   language: svelte
   rule:
     # Rule pattern here
   

3. Test your rule with ast-grep scan --rule rules/your-rule.yml

Related Projects

• AST-Grep: The structural search tool these rules are built for
• Tree-sitter Svelte: The Svelte parser used by these rules
• Svelte 5 Documentation: Official Svelte 5 documentation with runes and other new features