Svelte ESLint Parser

https://github.com/sveltejs/svelte-eslint-parser
Admin
A parser for Svelte components that integrates with ESLint, enabling custom rule creation and...
Tokens:66,098
Snippets:459
Trust Score:9.8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the development server with npm run dev

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/explorer-v2/README.md

Start the development server after installing dependencies. The --open flag opens the app in a new browser tab.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Install svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/README.md

Install the parser and ESLint as development dependencies.

```bash
npm install --save-dev eslint svelte-eslint-parser
```

--------------------------------

### svelte.config.js example

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/svelte-config.md

Example config file consumed when no explicit option is given. Shows compilerOptions.runes recognized by static analysis and notes that kit.files is extracted statically while other kit fields are typed but not evaluated.

```javascript
/** @type {import("svelte").Config} */
export default {
  compilerOptions: {
    runes: true, // recognized by static analysis
  },
  // extensions, preprocess, kit — carried through the SvelteConfig type
  // (kit.files is also extracted statically, other kit fields are typed but not evaluated)
};
```

--------------------------------

### Example: Reading Attributes and Directives

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-html-attributes.md

Example code showing how to parse a Svelte component and traverse AST nodes to read directives.

```APIDOC
## Example: Reading Attributes and Directives

### Description
This example demonstrates how to use `parseForESLint` and `traverseNodes` from `svelte-eslint-parser` to parse a Svelte component and inspect directives.

### Usage
```js
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(
  `<script>
     let value = "x";
     function onClick() {}
   </script>
   <input bind:value={value} on:click={onClick} class:foo style:color="red" {id} />`,
  { filePath: "Input.svelte" },
);

const seen = [];
traverseNodes(ast, {
  enterNode(node) {
    if (node.type === "SvelteDirective") {
      seen.push({
        kind: node.kind,          // "Binding" | "EventHandler"
        name: node.key.name /* SvelteName | Identifier */ ,
        modifiers: node.key.modifiers, // e.g. []
        shorthand: node.shorthand ?? undefined,
      });
    }
  },
  leaveNode() {},
});

console.log(seen.map((d) => d.kind)); // ["Binding", "EventHandler"]
console.log(seen[0].name.name);       // "value" (bind:value)
console.log(seen[1].name.name);       // "click" (on:click)
```
```

--------------------------------

### Usage example with parseForESLint and VisitorKeys

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/visitor-keys.md

Demonstrates importing parseForESLint and VisitorKeys, parsing a Svelte snippet, and accessing the keys for a mustache tag node.

```javascript
import { parseForESLint, VisitorKeys } from "svelte-eslint-parser";

const { ast } = parseForESLint(`<script>let x = 1;</script>{x}`, {
  filePath: "App.svelte",
});

// Keys for the mustache tag node
console.log(VisitorKeys.SvelteMustacheTag); // ["expression"]
// The parser also exposes the merged set:
// result.visitorKeys.SvelteElement etc.
```

--------------------------------

### Usage example with explicit svelteConfig

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/svelte-config.md

Shows how to import the Svelte config and pass it explicitly in parserOptions to bypass file discovery.

```javascript
import svelteConfig from "./svelte.config.js";

export default [
  {
    files: ["**/*.svelte"],
    languageOptions: {
      parser: svelteParser,
      parserOptions: {
        svelteConfig, // explicit — bypasses file discovery
      },
    },
  },
];
```

--------------------------------

### Build the production app with npm run build

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/explorer-v2/README.md

Build a production version of the app. Requires installing an adapter for the target environment first. Preview the built app with npm run preview, but do not use preview to serve in production.

```bash
npm run build
```

--------------------------------

### styleNodeLoc(node)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Converts a PostCSS node's source location to an ESLint-style location. The start column is adjusted from 1-based to 0-based, while the end column is passed through unchanged. Missing positions result in undefined values.

```APIDOC
## styleNodeLoc(node)

### Description
Converts a PostCSS node's source location to an ESLint-style location. The start column is adjusted from 1-based to 0-based, while the end column is passed through unchanged. Missing positions result in undefined values.

### Signature
```ts
export function styleNodeLoc(node: Node): Partial<SourceLocation>
```

### Parameters
- **node** (Node) - Required - Any PostCSS node with a `source`.

### Returns
- **Partial<SourceLocation>** - ESLint-style location. `start.column` is `source.start.column - 1`; `end.column` is passed through. Missing positions yield `undefined`.
```

--------------------------------

### Access Svelte parser services in create(context)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/services.md

Use this in a rule's create(context) to access Svelte parser services. Bail out early for non-Svelte files by checking services.isSvelte, then use services.getSvelteHtmlAst() to get the raw Svelte compiler AST of the template.

```javascript
export default {
  create(context) {
    const services = context.sourceCode.parserServices;

    // Svelte-only rules should bail on non-Svelte files
    if (!services || !services.isSvelte) {
      return {};
    }

    return {
      SvelteElement(node) {
        // Raw Svelte compiler AST of the template
        const fragment = services.getSvelteHtmlAst();
      },
    };
  },
};
```

--------------------------------

### PostCSS-based Svelte style rule usage

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Usage example for a PostCSS-based Svelte style rule. Shows how to access parser services, check for Svelte, and use styleNodeLoc and styleNodeRange on declaration nodes. The comment notes that styles are parsed lazily on demand.

```js
import postcss from "postcss"; // only for node-type checks

export default {
  create(context) {
    const services = context.sourceCode.parserServices;
    if (!services?.isSvelte) return {};

    return {
      "SvelteStyleElement > SvelteStartTag"(node) {
        // Called on start-tag open; parse styles lazily on demand
      },
    };
  },
};

// Direct usage outside rules:
const ctx = services.getStyleContext();
if (ctx.status === "success") {
  ctx.sourceAst.walk((node) => {
    if (node.type === "decl") {
      const loc = services.styleNodeLoc(node);
      const range = services.styleNodeRange(node);
      // loc → { start: { line, column }, end: { line, column } | undefined }
    }
  });
}
```

--------------------------------

### Complete ESLint config for Svelte with TypeScript

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/configuration.md

Complete ESLint flat config example for linting Svelte files. Uses svelte-eslint-parser with @typescript-eslint/parser for TypeScript, sets ecmaVersion 2022, enables runes, and includes project and extraFileExtensions for type-aware linting.

```js
import svelteParser from "svelte-eslint-parser";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.svelte", "**/*.svelte.js", "**/*.svelte.ts"],
    languageOptions: {
      parser: svelteParser,
      parserOptions: {
        sourceType: "module",
        ecmaVersion: 2022,
        ecmaFeatures: { jsx: false },
        parser: { ts: tsParser, js: "espree", typescript: tsParser },
        svelteConfig: undefined, // or import your svelte.config.js
        svelteFeatures: { runes: true },
        project: "tsconfig.json",
        extraFileExtensions: [".svelte"],
      },
    },
  },
];
```

--------------------------------

### src/main.ts public API

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

The entire src/main.ts file. It defines the public API: parseForESLint, AST, ParseError, VisitorKeys, meta, traverseNodes, and SvelteConfig. It also installs an opt-in ts.sys.readFile hook.

```typescript
import * as AST from "./ast/index.js";
import { traverseNodes } from "./traverse.js";
import { KEYS } from "./visitor-keys.js";
import { ParseError } from "./errors.js";
export {
  parseForESLint,
  type StyleContext,
  type StyleContextNoStyleElement,
  type StyleContextParseError,
  type StyleContextSuccess,
  type StyleContextUnknownLang,
} from "./parser/index.js";
export { name } from "./meta.js";
// If we use `export * as meta from "./meta.js"`,
// the structuredClone performed by eslint-plugin-prettier will fail,
// so we will need to re-export it as a plain object.
import * as metaModule from "./meta.js";
export const meta = { ...metaModule };
export type { SvelteConfig } from "./svelte-config/index.js";

export { AST, ParseError };

// Keys
export const VisitorKeys = KEYS;

// tools
export { traverseNodes };

// Opt-in `ts.sys.readFile` hook. See `ts-sys-hook.ts`.
import { installTsSysHook } from "./ts-sys-hook.js";
installTsSysHook();
```

--------------------------------

### styleSelectorNodeLoc(node)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Converts a postcss-selector-parser node's source location to an ESLint-style location. The start column is adjusted from 1-based to 0-based, while the end is passed through verbatim.

```APIDOC
## styleSelectorNodeLoc(node)

### Description
Converts a postcss-selector-parser node's source location to an ESLint-style location. The start column is adjusted from 1-based to 0-based, while the end is passed through verbatim.

### Signature
```ts
export function styleSelectorNodeLoc(
  node: SelectorNode,
): Partial<SourceLocation>
```

### Parameters
- **node** (SelectorNode) - Required - A `postcss-selector-parser` node.

### Returns
- **Partial<SourceLocation>** - ESLint-style location. `start.column` is `source.start.column - 1`; `end` is passed through verbatim.
```

--------------------------------

### Inspect parsed program AST

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-common.md

Example of inspecting a parsed program using parseForESLint. Shows how to access ast.type, ast.sourceType, ast.comments, and ast.tokens. The comments array includes line comments from the template, and tokens include both script and HTML token types.

```js
import { parseForESLint } from "svelte-eslint-parser";

const { ast } = parseForESLint(`<script>const x = 1;</script>\n<!-- hi -->\n<p>{x}</p>`);

console.log(ast.type);         // "Program"
console.log(ast.sourceType);   // "module"
console.log(ast.comments.map((c) => [c.type, c.value]));
// [["Line", " hi "]...] depending on script/template comment split
console.log(ast.tokens.map((t) => t.type)); // includes "Punctuator", "HTMLText", ...
```

--------------------------------

### addAllReferences(list, elements)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/scope.md

Inserts all references from an array into a list sorted by reference identifier range start.

```APIDOC
## addAllReferences(list, elements)

### Description
Inserts all references from `elements` into `list` sorted by `reference.identifier.range[0]`.

### Signature
```ts
export function addAllReferences(
  list: eslint.Scope.Reference[],
  elements: eslint.Scope.Reference[],
): void
```

### Parameters
- `list` (eslint.Scope.Reference[]) - Required - The list to insert references into.
- `elements` (eslint.Scope.Reference[]) - Required - The references to insert.

### Returns
`void`
```

--------------------------------

### Traversing Svelte Block Nodes with traverseNodes

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-html-blocks.md

Use this example to traverse Svelte AST nodes with `traverseNodes` from `svelte-eslint-parser`. It parses a Svelte template containing `{#each}` and `{#if}` blocks, then collects information about each `SvelteEachBlock` node, including its context, index, key type, and whether it has an `{:else}` branch. The output logs the number of `SvelteEachBlock` nodes found (1).

```javascript
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(
  `{#each items as item, i (item.id)}
     {#if item.done}
       <p>{item.label}</p>
     {:else if i === 0}
       <p>first</p>
     {:else}
       <p>{i}: {item.label}</p>
     {/if}
   {:else}
     <p>empty</p>
   {/each}`,
  { filePath: "List.svelte" },
);

const eachs = [];
traverseNodes(ast, {
  enterNode(node) {
    if (node.type === "SvelteEachBlock") {
      eachs.push({
        context: node.context && node.context.name, // "item"
        index: node.index && node.index.name,       // "i"
        key: node.key.type,                          // ESTree expression
        hasElse: node.else !== null,                 // true
      });
    }
  },
  leaveNode() {},
});
console.log(eachs.length); // 1
```

--------------------------------

### Test seam functions _resetTranslationCacheForTesting and _patchTsSysForTesting

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ts-sys-hook.md

Underscore-prefixed functions for testing only. Reset clears the translation map and stored options; patch installs the wrapper on a caller-supplied sys object.

```ts
export function _resetTranslationCacheForTesting(): void
export function _patchTsSysForTesting(sys: TsLike["sys"]): void
```

--------------------------------

### Access svelteConfig in a rule

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/svelte-config.md

Use `context.sourceCode.parserServices.svelteParseContext.svelteConfig` to access the parsed Svelte config. The `svelteConfig` may be `null` (no config found) or `{}` (found but nothing statically extractable). The example checks if `compilerOptions.runes` is explicitly `false` to detect non-runes mode.

```javascript
export default {
  create(context) {
    const services = context.sourceCode.parserServices;
    const { svelteConfig } = services.svelteParseContext;
    if (svelteConfig?.compilerOptions?.runes === false) {
      // file is in non-runes mode
    }
    return {};
  },
};
```

--------------------------------

### Detect reactive statements with parseForESLint

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-script.md

Example that parses a Svelte component with reactive statements and traverses the AST to collect SvelteReactiveStatement nodes.

```js
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(
  `<script>
     let count = 0;
     $: doubled = count * 2;
     $: console.log("count is", count);
   </script>
   <button on:click={() => count++}>{doubled}</button>`,
  { filePath: "Counter.svelte" },
);

const reactives = [];
traverseNodes(ast, {
  enterNode(node) {
    if (node.type === "SvelteReactiveStatement") {
      reactives.push({
        labelName: node.label.name, // "$"
        bodyType: node.body.type,   // e.g. "ExpressionStatement"
      });
    }
  },
  leaveNode() {},
});
console.log(reactives.length); // 2
```

--------------------------------

### Usage example: mutating scopes in a rule

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/scope.md

Shows how to mutate scopes in a rule by removing scope info from a SvelteEachBlock node. Imports removeAllScopeAndVariableAndReference from svelte-eslint-parser/lib/scope/index.js and uses context.sourceCode.scopeManager.

```js
import { removeAllScopeAndVariableAndReference } from "svelte-eslint-parser/lib/scope/index.js";

export default {
  create(context) {
    const scopeManager = context.sourceCode.scopeManager;
    if (!scopeManager) return {};
    return {
      SvelteEachBlock(node) {
        // Example: re-analyze the each-block without its scope info
        removeAllScopeAndVariableAndReference(node, { scopeManager });
      },
    };
  },
};
```

--------------------------------

### Read style context with getStyleContext

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/services.md

Use this to read the style context from parser services. Handle the status values: success (with sourceLang and sourceAst), unknown-lang, parse-error, and the else branch for no <style> element. Use styleNodeLoc and styleNodeRange to get ESLint-style locations and ranges.

```javascript
const ctx = services.getStyleContext();
if (ctx.status === "success") {
  // ctx.sourceLang ("css" | "postcss" | "scss") and ctx.sourceAst (PostCSS Root)
  ctx.sourceAst.walk((node) => {
    const loc = services.styleNodeLoc(node); // ESLint-style location
    const range = services.styleNodeRange(node); // ESLint-style range
  });
} else if (ctx.status === "unknown-lang") {
  // style with lang not in {css, postcss, scss}
} else if (ctx.status === "parse-error") {
  // ctx.error — PostCSS parse failure
} else {
  // no <style> element
}
```

--------------------------------

### Create a new Svelte project with npm init svelte@next

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/explorer-v2/README.md

Use these commands to scaffold a new Svelte project. The first creates a project in the current directory, the second in a subdirectory named my-app. The @next tag is temporary.

```bash
# create a new project in the current directory
npm init svelte@next

# create a new project in my-app
npm init svelte@next my-app
```

--------------------------------

### parseSelector(rule) - parse PostCSS rule selector

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Parses a PostCSS Rule's selector into a SelectorRoot using postcss-selector-parser. All selector nodes get file-relative locations via fixSelectorNodeLocation; if the rule lacks a resolvable start location, the node's source.start/source.end are set to undefined.

```ts
export function parseSelector(rule: Rule): SelectorRoot
```

--------------------------------

### installTsSysHook()

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ts-sys-hook.md

Activates the experimental `ts.sys.readFile` hook for type-aware linting of `.svelte` files.

```APIDOC
## installTsSysHook()

### Description
Idempotent function that activates the experimental `ts.sys.readFile` hook. It is a no-op unless the environment variable `SVELTE_ESLINT_PARSER_EXPERIMENTAL_TS_SYS_HOOK` is set to `"1"`. When enabled, it force-loads the project's TypeScript, patches all cached TypeScript instances, and registers a diagnostic on process exit.

### Signature
```ts
export function installTsSysHook(): void
```

### Parameters
None.

### Returns
`void`

### Behavior
- No-op unless `process.env[SVELTE_ESLINT_PARSER_EXPERIMENTAL_TS_SYS_HOOK] === "1"`.
- Force-loads the project's `typescript` via `loadNewestModule`.
- Patches every `typescript.js` already in the CJS require cache.
- Registers a `process.on("exit")` diagnostic that warns if `.svelte` files were primed but `ts.sys.readFile` was never called for them.
- Emits a startup line to stderr on every lint run.
```

--------------------------------

### SvelteFunctionBindingsExpression interface

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-script.md

Interface for the SvelteFunctionBindingsExpression node representing a `bind:name={get, set}` expression.

```ts
/** Node of `bind:name={get, set}` expression. */
export interface SvelteFunctionBindingsExpression extends BaseNode {
  type: "SvelteFunctionBindingsExpression";
  expressions: [
    /** Getter */
    ESTree.Expression,
    /** Setter */
    ESTree.Expression,
  ];
  parent: SvelteBindingDirective;
}
```

--------------------------------

### addReference(list, reference)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/scope.md

Inserts a reference into a list sorted by the reference identifier's range start.

```APIDOC
## addReference(list, reference)

### Description
Inserts a reference into a list sorted by `reference.identifier.range[0]`.

### Signature
```ts
export function addReference(
  list: eslint.Scope.Reference[],
  reference: eslint.Scope.Reference,
): void
```

### Parameters
- `list` (eslint.Scope.Reference[]) - Required - The list of references to insert into.
- `reference` (eslint.Scope.Reference) - Required - The reference to insert.

### Returns
`void`
```

--------------------------------

### SvelteStartTag interface

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/docs/AST.md

Defines the SvelteStartTag node representing the start tag of an element, including its attributes and self-closing flag.

```ts
interface SvelteStartTag extends Node {
  type: "SvelteStartTag";
  attributes: (
    | SvelteAttribute
    | SvelteShorthandAttribute
    | SvelteSpreadAttribute
    | SvelteAttachTag
    | SvelteDirective
    | SvelteStyleDirective
    | SvelteSpecialDirective
    | SvelteGenericsDirective
  )[];
  selfClosing: boolean;
}
```

--------------------------------

### Import svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

Shows how to import the parser and its named exports from the package root.

```APIDOC
## Import svelte-eslint-parser

### Description
Import the parser as a default or named exports from the package root.

### Import Path
`svelte-eslint-parser`

### Example
```js
import svelteParser from "svelte-eslint-parser";
// or
import { parseForESLint, ParseError, AST, VisitorKeys, meta, traverseNodes } from "svelte-eslint-parser";
```
```

--------------------------------

### Import VisitorKeys from svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/visitor-keys.md

Shows how to import the VisitorKeys constant, including the internal name KEYS from the lib path.

```javascript
import { VisitorKeys } from "svelte-eslint-parser";
// internal name:
import { KEYS } from "svelte-eslint-parser/lib/visitor-keys.js";
```

--------------------------------

### Detect function bindings with parseForESLint

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-script.md

Example that parses a Svelte component with a function binding and traverses the AST to collect SvelteFunctionBindingsExpression nodes.

```js
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(
  `<script>let a = 1; function get() { return a; } function set(v) { a = v; }</script>
   <input bind:value={get, set} />`,
  { filePath: "Bind.svelte" },
);

const bindings = [];
traverseNodes(ast, {
  enterNode(node) {
    if (node.type === "SvelteFunctionBindingsExpression") {
      bindings.push([node.expressions[0].type, node.expressions[1].type]);
      // parent.kind === "Binding"
    }
  },
  leaveNode() {},
});
console.log(bindings); // [["Identifier", "Identifier"]]
```

--------------------------------

### getKeys

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/traverse.md

Documentation for the getKeys helper function.

```APIDOC
## getKeys

### Description
Returns the visitor-keys entry for `node.type` (or the fallback keys), filtered to keys that yield at least one node.

### Signature
```ts
export function getKeys(
  node: any,
  visitorKeys?: VisitorKeys | TSESVisitorKeys,
): string[];
```

### Parameters
- **node** (any) - Required - The node to inspect.
- **visitorKeys** (VisitorKeys | TSESVisitorKeys) - Optional - Custom visitor keys to use.

### Return Value
`string[]` - The list of keys that yield at least one node.
```

--------------------------------

### Activation command with SVELTE_ESLINT_PARSER_EXPERIMENTAL_TS_SYS_HOOK

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ts-sys-hook.md

Run ESLint with the experimental hook enabled. The environment variable must be set to "1" to activate; any other value disables it.

```sh
SVELTE_ESLINT_PARSER_EXPERIMENTAL_TS_SYS_HOOK=1 eslint --no-cache --concurrency auto .
```

--------------------------------

### Import parseForESLint from svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Shows how to import the parser. StyleContext types are reachable through the parse result or services.

```js
import { parseForESLint } from "svelte-eslint-parser";
// StyleContext types are reachable through the parse result / services.
```

--------------------------------

### meta

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

Plain object containing package metadata (e.g., name, version).

```APIDOC
## meta

### Description
Plain object with package metadata. Re-exported as a plain object to avoid structuredClone issues.

### Usage
```js
import { meta } from "svelte-eslint-parser";
```
```

--------------------------------

### styleNodeRange(node)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/style-context.md

Returns the range of a PostCSS node as a tuple of start and end offsets. The end offset is incremented by 1 to be exclusive. If the node has no source, returns [undefined, undefined].

```APIDOC
## styleNodeRange(node)

### Description
Returns the range of a PostCSS node as a tuple of start and end offsets. The end offset is incremented by 1 to be exclusive. If the node has no source, returns [undefined, undefined].

### Signature
```ts
export function styleNodeRange(
  node: Node,
): [number | undefined, number | undefined]
```

### Parameters
- **node** (Node) - Required - Any PostCSS node with a `source`.

### Returns
- **[number | undefined, number | undefined]** - `[startOffset, endOffset + 1]` from the PostCSS `source`, or `[undefined, undefined]` when `node.source` is absent.
```

--------------------------------

### installTsSysHook() function signature

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ts-sys-hook.md

Idempotent function that activates the hook. No-op unless the environment variable is set to "1". When enabled, it force-loads TypeScript, patches cached instances, and registers an exit diagnostic.

```ts
export function installTsSysHook(): void
```

--------------------------------

### src/index.ts entry point

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

The entire src/index.ts file. It re-exports everything from main.js and provides a default export.

```typescript
export * from "./main.js";
export * as default from "./main.js";
```

--------------------------------

### SvelteStartTag and SvelteEndTag interfaces

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-html-elements.md

Defines the AST node types for start and end tags of Svelte elements. SvelteStartTag includes attributes and selfClosing flag; SvelteEndTag has no extra properties. Both have a parent that can be a SvelteElement, SvelteScriptElement, or SvelteStyleElement.

```typescript
export interface SvelteStartTag extends BaseNode {
  type: "SvelteStartTag";
  attributes: (
    | SvelteAttribute
    | SvelteShorthandAttribute
    | SvelteSpreadAttribute
    | SvelteAttachTag
    | SvelteDirective
    | SvelteStyleDirective
    | SvelteSpecialDirective
    | SvelteGenericsDirective
  )[];
  selfClosing: boolean;
  parent: SvelteElement | SvelteScriptElement | SvelteStyleElement;
}
export interface SvelteEndTag extends BaseNode {
  type: "SvelteEndTag";
  parent: SvelteElement | SvelteScriptElement | SvelteStyleElement;
}
```

--------------------------------

### Virtual script generation for each block scoping

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/docs/internal-mechanism.md

Demonstrates how the parser generates virtual script code for {#each} and {@const} blocks to correctly scope variables like `e` within the each block.

```svelte
<script lang="ts">
  const array = [1, 2, 3];
</script>

{#each array as e}
  {@const ee = e * 2}
  {ee}
{/each}
```

```ts
const array = [1, 2, 3];
function $_render1() {
  Array.from(array).forEach((e) => {
    const ee = e * 2;
    ee;
  });
}
```

--------------------------------

### Reading Svelte directives with traverseNodes

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-html-attributes.md

Example using `parseForESLint` and `traverseNodes` to read Svelte directives from an input component. It collects `SvelteDirective` nodes and logs their kinds and names, showing how to access `kind`, `key.name`, `modifiers`, and `shorthand`.

```js
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(
  `<script>
     let value = "x";
     function onClick() {}
   </script>
   <input bind:value={value} on:click={onClick} class:foo style:color="red" {id} />`,
  { filePath: "Input.svelte" },
);

const seen = [];
traverseNodes(ast, {
  enterNode(node) {
    if (node.type === "SvelteDirective") {
      seen.push({
        kind: node.kind,          // "Binding" | "EventHandler"
        name: node.key.name /* SvelteName | Identifier */ ,
        modifiers: node.key.modifiers, // e.g. []
        shorthand: node.shorthand ?? undefined,
      });
    }
  },
  leaveNode() {},
});

console.log(seen.map((d) => d.kind)); // ["Binding", "EventHandler"]
console.log(seen[0].name.name);       // "value" (bind:value)
console.log(seen[1].name.name);       // "click" (on:click)
```

--------------------------------

### Basic svelte-eslint-parser configuration

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/README.md

Basic ESLint flat config using svelte-eslint-parser with parserOptions matching espree defaults. Set sourceType, ecmaVersion, and ecmaFeatures as needed.

```javascript
import svelteParser from "svelte-eslint-parser";

export default [
  // ...
  {
    files: [
      // Set .svelte/.js/.ts files. See above for more details.
    ],
    languageOptions: {
      parser: svelteParser,
      parserOptions: {
        sourceType: "module",
        ecmaVersion: 2024,
        ecmaFeatures: {
          globalReturn: false,
          impliedStrict: false,
          jsx: false,
        },
      },
    },
  },
];
```

--------------------------------

### primeTranslationCache(filePath, virtualCode)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ts-sys-hook.md

Seeds the translation cache for a `.svelte` file.

```APIDOC
## primeTranslationCache(filePath, virtualCode)

### Description
Seeds the mtime-keyed translation cache so that later `ts.sys.readFile(filePath)` hits are served from cache. Called by `parseTypeScriptInSvelte`.

### Signature
```ts
export function primeTranslationCache(
  filePath: string,
  virtualCode: string,
): void
```

### Parameters
- `filePath` (string) - Required - The path of the `.svelte` file.
- `virtualCode` (string) - Required - The virtual TypeScript translation for the file.

### Returns
`void`

### Behavior
- Stores the virtual code in the translation cache keyed by mtime.
```

--------------------------------

### Run ESLint on Svelte files

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/README.md

Run ESLint on JavaScript and Svelte files in the src directory.

```bash
eslint "src/**/*.{js,svelte}"
```

--------------------------------

### TypeScript type inference issue in Svelte reactive statements

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/docs/internal-mechanism.md

Shows the type inference problem in Svelte: TypeScript infers `foo` as `null` inside `$:` statements, causing `foo.bar` to be flagged as `never`. This is the motivating example for the parser's virtual code generation.

```ts
export let foo: { bar: number } | null = null;

$: console.log(foo && foo.bar);
                   // ^ never type
```

--------------------------------

### parseForESLint(code, options)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/parse-for-eslint.md

Documentation for the parseForESLint function, the main entry point for parsing Svelte files in ESLint.

```APIDOC
## parseForESLint(code, options)

### Description
Parses Svelte source code (`.svelte`, `.svelte.js`, `.svelte.ts`) for ESLint, returning an AST, services, visitor keys, and scope manager.

### Parameters
- **code** (`string`) - Required - Raw source code of the file to parse.
- **options** (`any`) - Optional - Raw `parserOptions` from the ESLint config. Recognized keys: anything accepted by `espree` (e.g. `ecmaVersion`, `sourceType`, `ecmaFeatures`), plus Svelte-specific `parser`, `svelteConfig`, `svelteFeatures`, `filePath`, and `extraFileExtensions`.

### Return Value
Returns a `ParseResult` (ESLintExtendedProgram shape) with the following fields:
- **ast** (`SvelteProgram`) - The syntax tree. For `.svelte` files it is a `SvelteProgram` root (`type: "Program"`) whose `body` mixes script elements, style elements, and template child nodes, with `parent` links, `tokens`, and `comments` populated. For `.svelte.js`/`.svelte.ts` files the root is a plain ESTree/TSESTree `Program`.
- **services** (`Record<string, any>`) - Services returned by the underlying script parser, merged with Svelte services. For rules, both the typescript-eslint services (e.g. `program`, `esTreeNodeToTSNodeMap`) and the Svelte helpers are available here.
- **visitorKeys** (`{ [type: string]: string[] }`) - `KEYS` merged with the script parser's visitor keys.
- **scopeManager** (`eslint.Scope.ScopeManager`) - Scope analysis over the whole file.

### Behavioral Differences per Input

#### `.svelte` files
- Parses template with `svelte/compiler` and script with the configured script parser.
- Throws `ParseError("The script is unterminated", ...)` if statements remain after attaching all `SvelteScriptElement.body` arrays — i.e. there is script code that does not belong to any `<script>` element.
- `ast.sourceType` is taken from the script parse result.
- `services.isSvelte` is `true`, `services.isSvelteScript` is `false`.
- Adds `$$slots`, `$$props`, `$$restProps` (+ runes globals when runes mode is active) as globals to the scope manager.

#### `.svelte.js` / `.svelte.ts` files
- Parsed as a plain script (Svelte 5 "rune symbols in JS files" support).
- `services.isSvelte` is `false`, `services.isSvelteScript` is `true`.
- Runes mode is forced to `svelteVersion.gte(5)`.
- Globals injected: runes globals only (`$state`, `$derived`, `$effect`, `$props`, `$bindable`, `$inspect`, `$host`). Non-runes globals for `.svelte`: `$$slots`, `$$props`, `$$restProps`.
```

--------------------------------

### getFallbackKeys

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/traverse.md

Documentation for the getFallbackKeys helper function.

```APIDOC
## getFallbackKeys

### Description
Returns the keys of a node that are considered "node-like" (i.e., not comments, loc, parent, range, tokens, etc.) and whose value is a non-null object with a string `type`, or an array.

### Signature
```ts
export function getFallbackKeys(node: any): string[];
```

### Parameters
- **node** (any) - Required - The node to inspect.

### Return Value
`string[]` - The list of keys that are node-like.
```

--------------------------------

### Enable Svelte runes mode in ESLint flat config

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/configuration.md

ESLint flat config example enabling Svelte runes mode via parserOptions.svelteFeatures.runes. Use when you need ESLint to recognize rune symbols like $state, $derived, $effect, $props, $bindable, $inspect, and $host, plus $$slots/$$props/$$restProps globals. Setting runes to true forces runes mode on; unset defaults to true for Svelte 5, while Svelte 3/4 always use false.

```javascript
export default [
  {
    files: ["**/*.svelte"],
    languageOptions: {
      parser: svelteParser,
      parserOptions: {
        svelteFeatures: { runes: true },
      },
    },
  },
];
```

--------------------------------

### Visitor Keys for Svelte AST Nodes

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-html-attributes.md

Visitor keys for Svelte AST nodes, indicating which child nodes are traversed.

```APIDOC
## Visitor Keys for Svelte AST Nodes

### Description
These are the `VisitorKeys` entries that define which child nodes are visited for each Svelte AST node type. They are used by the parser's traversal mechanism.

### Visitor Keys
- `SvelteAttribute` → `["key", "value"]`
- `SvelteShorthandAttribute` → `["key", "value"]`
- `SvelteSpreadAttribute` → `["argument"]`
- `SvelteAttachTag` → `["expression"]`
- `SvelteDirective` → `["key", "expression"]`
- `SvelteStyleDirective` → `["key", "value"]`
- `SvelteSpecialDirective` → `["key", "expression"]`
- `SvelteGenericsDirective` → `["key", "params"]`
- `SvelteDirectiveKey` → `["name"]`
```

--------------------------------

### Import svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/parse-for-eslint.md

Import the parser module or the parseForESLint function directly. The comment shows the alternative import style.

```js
import svelteParser from "svelte-eslint-parser";
// or
import { parseForESLint } from "svelte-eslint-parser";
```

--------------------------------

### traverseNodes(ast, visitor)

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/traverse.md

Documentation for the traverseNodes function from svelte-eslint-parser, including usage, parameters, and error handling.

```APIDOC
## traverseNodes(ast, visitor)

### Description
Traverses the AST returned by `parseForESLint` and calls the provided visitor callbacks for each node. It is used to walk the Svelte AST and collect or inspect nodes.

### Method
Function call

### Endpoint
`traverseNodes(ast, visitor)`

### Parameters
- **ast** (ASTNode) - Required - The AST returned from `parseForESLint`.
- **visitor** (object) - Required - An object with `enterNode` and `leaveNode` callbacks.
  - **enterNode(node, parent)** (function) - Required - Called when entering a node. Receives the node and its parent (or `null` for the root).
  - **leaveNode(node)** (function) - Optional - Called when leaving a node.
  - **visitorKeys** (object) - Optional - Custom visitor keys to control traversal. Prefer the parser's `result.visitorKeys` for merged keys.

### Request Example
```js
import { parseForESLint, traverseNodes } from "svelte-eslint-parser";

const { ast } = parseForESLint(`<script>const a = 1;</script><p>{a}</p>`, {
  filePath: "App.svelte",
});

const mustaches = [];
traverseNodes(ast, {
  enterNode(node, parent) {
    if (node.type === "SvelteMustacheTag") {
      mustaches.push({ node, parent: parent && parent.type });
    }
  },
  leaveNode() {
    // no-op
  },
});
console.log(mustaches.length); // 1
```

### Response
#### Success Response
- **void** - The function does not return a value; it only invokes the visitor callbacks.

#### Response Example
```js
// No return value; side effects occur in the visitor callbacks.
```

### Error Handling
`traverseNodes` does not throw under normal circumstances. It only iterates and calls the visitor. If a node has a malformed key configuration, the fallback path is used instead of failing. Errors are only expected if user callbacks throw or the root is not node-like.
```

--------------------------------

### Definition of KEYS in src/visitor-keys.ts

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/visitor-keys.md

KEYS is created by merging svelteKeys with standard ESLint keys using unionWith from eslint-visitor-keys, typed as SourceCode.VisitorKeys.

```typescript
export const KEYS: SourceCode.VisitorKeys = unionWith(
  svelteKeys,
) as SourceCode.VisitorKeys;
```

--------------------------------

### Usage with Custom Visitor Keys

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/traverse.md

Traverses an AST with a custom visitorKeys object, here using the parser's VisitorKeys. The enterNode callback can access SvelteEachBlock properties like expression, context, index, key, children, and else. Prefer result.visitorKeys for rule authors as it merges Svelte and script parser keys.

```js
import { parseForESLint, traverseNodes, VisitorKeys } from "svelte-eslint-parser";

const { ast } = parseForESLint(`<ul>{#each items as item}<li>{item}</li>{/each}</ul>`);

traverseNodes(ast, {
  visitorKeys: VisitorKeys, // or, preferably, the parser's own `result.visitorKeys` (Svelte keys + script-parser keys)
  enterNode(node) {
    if (node.type === "SvelteEachBlock") {
      // node.expression, node.context, node.index, node.key, node.children, node.else
    }
  },
  leaveNode() {},
});
```

--------------------------------

### Import svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

Import the parser at the package root. The package is ESM-only and the supported API consists only of the symbols re-exported by lib/index.js.

```javascript
import svelteParser from "svelte-eslint-parser";
// or
import { parseForESLint, ParseError, AST, VisitorKeys, meta, traverseNodes } from "svelte-eslint-parser";
```

--------------------------------

### Import ParseError from svelte-eslint-parser

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/parse-error.md

Import the ParseError class from the svelte-eslint-parser package.

```js
import { ParseError } from "svelte-eslint-parser";
```

--------------------------------

### VisitorKeys

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

Object mapping AST node types to their child keys, used for traversal.

```APIDOC
## VisitorKeys

### Description
Mapping of AST node types to visitor keys, used for traversing the AST.

### Usage
```js
import { VisitorKeys } from "svelte-eslint-parser";
```
```

--------------------------------

### traverseNodes

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/traverse.md

Documentation for the traverseNodes function, which traverses an AST in pre-order with enter and leave callbacks.

```APIDOC
## traverseNodes

### Description
Traverses an AST in pre-order, calling `enterNode` before descending into children and `leaveNode` after. The `parent` argument is `null` for the root node. Child lookup uses `visitor.visitorKeys` if given, otherwise the bundled `KEYS` map; unknown node types fall back to `getFallbackKeys`.

### Signature
```ts
traverseNodes(
  node: SvelteNode | ESTree.Node | TSESTree.Node,
  visitor: Visitor,
  visitorKeys?: VisitorKeys | TSESVisitorKeys,
): void
```

### Parameters
- **node** (SvelteNode | ESTree.Node | TSESTree.Node) - Required - The root node of the AST to traverse.
- **visitor** (Visitor) - Required - An object with `enterNode` and `leaveNode` callbacks.
- **visitorKeys** (VisitorKeys | TSESVisitorKeys) - Optional - Custom visitor keys to use for child lookup.

### Return Value
`void`.

### Behavior Notes
- Traversal descends only into "node-like" values: objects with a string `type`, and arrays thereof. Other properties (including `parent`, `loc`, `range`) are skipped.
- `getKeys` filters the keys map through `getNodes(...).next().done` — i.e. keys whose value is not a node/array-of-nodes are dropped.
- AST `parent` links are *not* set by `traverseNodes` itself. The parser sets them in `parseScriptInSvelte` via an `enterNode` callback that assigns `(node as any).parent = parent`. Consumers traversing a fresh tree with `traverseNodes` must link parents themselves or rely on the parser having already done so.
```

--------------------------------

### parseForESLint

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/parse-for-eslint.md

Documentation for the parseForESLint function, the main entry point for the svelte-eslint-parser custom parser.

```APIDOC
## parseForESLint

### Description
Parses Svelte source code and returns a result object conforming to the ESLint custom parser protocol. This is the main entry point for using svelte-eslint-parser with ESLint.

### Method
parseForESLint

### Signature
```ts
parseForESLint(code: string, options?: any): ParseResult
```

### Parameters
- **code** (string) - Required - The Svelte source code to parse.
- **options** (any) - Optional - Parser options.

### Return Value
Returns a `ParseResult` object with the following properties:
- **ast** (SvelteProgram) - The parsed AST.
- **services** (Record<string, any> & union) - Parser services. When parsing a Svelte file (`isSvelte: true`), includes methods like `getSvelteHtmlAst`, `getStyleContext`, `getStyleSelectorAST`, `styleNodeLoc`, `styleNodeRange`, `styleSelectorNodeLoc`, and `svelteParseContext`. When parsing a script-only file (`isSvelteScript: true`), includes `svelteParseContext`.
- **visitorKeys** ({ [type: string]: string[] }) - Visitor keys for AST traversal.
- **scopeManager** (eslint.Scope.ScopeManager) - The scope manager.

### Usage Example
```js
import { parseForESLint } from "svelte-eslint-parser";

const result = parseForESLint(code, options);
```
```

--------------------------------

### AST

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/index.md

Namespace containing AST node type definitions for Svelte.

```APIDOC
## AST

### Description
Namespace with AST node types for Svelte. Used for type checking and traversal.

### Usage
```js
import { AST } from "svelte-eslint-parser";
```
```

--------------------------------

### Visitor keys for script nodes

Source: https://github.com/sveltejs/svelte-eslint-parser/blob/main/_autodocs/api-reference/ast-script.md

Visitor keys for the script-side nodes, used for traversal.

```ts
SvelteReactiveStatement: ["label", "body"],
SvelteFunctionBindingsExpression: ["expressions"],
```
Tokens:
Raw