# sveld

**Repository Path**: mirrors_ibm/sveld

## Basic Information

- **Project Name**: sveld
- **Description**: Generate TypeScript definitions for your Svelte components
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-11-23
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sveld

[![NPM][npm]][npm-url]
![npm downloads to date](https://img.shields.io/npm/dt/sveld?color=262626&style=for-the-badge)

`sveld` generates TypeScript definitions and component documentation (Markdown/JSON) for Svelte components. It statically analyzes props, events, slots, module exports, context, and `$$restProps`. Add types with [JSDoc](https://jsdoc.app/) when inference is not enough.

The goal is to get third-party Svelte libraries working with the Svelte Language Server and TypeScript with minimal effort from the author. Generated `.d.ts` files give you autocomplete in VS Code and other IDEs.

[Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata.

`sveld` parses `.svelte` files with its own template parser (`src/template-parse/`), kept in parity with `svelte/compiler`'s parser by a differential test suite. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, and Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …). It also covers Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).

For `lang="ts"` components, `sveld` keeps source-level prop type annotations when it can, instead of forcing JSDoc. That covers legacy `export let` props, typed `$props()` destructuring (whole-object and per-prop), local `interface`/`type`/`enum` declarations, and TypeScript signatures on accessor exports (`export function`). Any type a prop annotation or accessor signature depends on — whether imported with `import type` or as a plain value import used only in a type position — is re-emitted as an `import type` at the top of the generated `.d.ts`, and local `interface`/`type`/`enum` declarations it depends on are copied alongside it. Everything stays textual: no semantic expansion, and `satisfies`/`as` are treated alike. A `const enum` is widened to a literal union of its member values instead of being re-declared, since `const enum` isn't supported by common bundlers under `isolatedModules`.

By default, generated `.d.ts` files extend `SvelteComponentTyped` from `svelte`, so TypeScript and the Svelte Language Server work whether consumers use Svelte 3, Svelte 4, or Svelte 5. Set `typesOptions.format: "component"` to instead emit the Svelte 5 `Component` type; see [`typesOptions.format`](#typesoptionsformat).

## When to use sveld

SvelteKit's library tooling (`svelte-package`) and `svelte2tsx` already emit `.d.ts` files for SvelteKit-based projects, so start there if that's your setup. `sveld` targets JS-first Svelte libraries: components authored in plain JavaScript with JSDoc rather than `lang="ts"`, where you still want full editor types without adopting TypeScript. It also covers cases `svelte-package` doesn't: generating JSON and Markdown component docs from the same source as the types, checking for API drift between releases (`--check`), and deriving richer types from JSDoc tags (`@typedef`, `@callback`, `@slot`, context types) than plain type inference produces.

---

From a Svelte component, `sveld` can infer basic prop types and emit definitions the [Svelte Language Server](https://github.com/sveltejs/language-tools) understands:

**Button.svelte**

```svelte
<script>
  export let type = "button";
  export let primary = false;
</script>

<button {...$$restProps} {type} class:primary on:click>
  <slot>Click me</slot>
</button>
```

The following generated `.d.ts` extends `SvelteComponentTyped`:

**Button.svelte.d.ts**

```ts
import { SvelteComponentTyped } from "svelte";
import type { SvelteHTMLElements } from "svelte/elements";

type $RestProps = SvelteHTMLElements["button"];

type $Props = {
  /**
   * @default "button"
   */
  type?: string;

  /**
   * @default false
   */
  primary?: boolean;

  [key: `data-${string}`]: unknown;
};

export type ButtonProps = Omit<$RestProps, keyof $Props> & $Props;

export default class Button extends SvelteComponentTyped<
  ButtonProps,
  { click: WindowEventMap["click"] },
  { default: Record<string, never> }
> {}
```

`sveld` adds the `[key: \`data-${string}\`]: unknown;` index signature whenever `$$restProps` is spread onto an element, so callers can pass arbitrary `data-*` attributes.

Inference only gets you so far. Use [JSDoc](https://jsdoc.app/) to document prop, event, and slot types when you need more precision.

```js
/** @type {"button" | "submit" | "reset"} */
export let type = "button";

/**
 * Set to `true` to use the primary variant
 */
export let primary = false;
```

With JSDoc, the output looks like this:

```ts
import { SvelteComponentTyped } from "svelte";
import type { SvelteHTMLElements } from "svelte/elements";

type $RestProps = SvelteHTMLElements["button"];

type $Props = {
  /**
   * @default "button"
   */
  type?: "button" | "submit" | "reset";

  /**
   * Set to `true` to use the primary variant
   * @default false
   */
  primary?: boolean;
};

export type ButtonProps = Omit<$RestProps, keyof $Props> & $Props;

export default class Button extends SvelteComponentTyped<
  ButtonProps,
  { click: WindowEventMap["click"] },
  { default: Record<string, never> }
> {}
```

---

## Table of Contents

- [When to use sveld](#when-to-use-sveld)
- [Approach](#approach)
- [Features](#features)
  - [`.d.ts` output format (`typesOptions.format`)](#dts-output-format-typesoptionsformat)
  - [Opt-in semantic resolution (`resolveTypes`)](#opt-in-semantic-resolution-resolvetypes)
  - [Persistent parse cache (`cache`)](#persistent-parse-cache-cache)
  - [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples)
  - [Type inference diagnostics](#type-inference-diagnostics)
    - [Diagnostic codes](#diagnostic-codes)
    - [Severity and `--strict=errors`](#severity-and---stricterrors)
    - [Ignoring diagnostics](#ignoring-diagnostics)
- [Requirements](#requirements)
- [Usage](#usage)
  - [Installation](#installation)
  - [Vite](#vite)
  - [CLI](#cli)
  - [Exit codes](#exit-codes)
  - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
  - [CI: strictness profiles (`--strict=ci`/`--strict=local`)](#ci-strictness-profiles---strictci---strictlocal)
  - [Node.js](#nodejs)
  - [Browser](#browser)
  - [Config File](#config-file)
  - [Publishing to NPM](#publishing-to-npm)
- [Available Options](#available-options)
- [Documenting Entry Exports](#documenting-entry-exports)
- [JSON Output](#json-output)
- [Custom Elements Manifest](#custom-elements-manifest)
  - [Consuming the manifest](#consuming-the-manifest)
- [llms.txt Output](#llmstxt-output)
- [Custom Writers](#custom-writers)
  - [The `OutputWriter` contract](#the-outputwriter-contract)
  - [Registering a writer](#registering-a-writer)
  - [Running it via the plugin](#running-it-via-the-plugin)
  - [Worked example: a `components.txt` name-list writer](#worked-example-a-componentstxt-name-list-writer)
- [API Reference](#api-reference)
  - [reactive](#reactive)
  - [binding](#binding)
  - [@type](#type)
  - [@default](#default)
  - [@typedef](#typedef)
  - [@property](#property)
  - [@callback](#callback)
  - [@slot / @snippet](#slot--snippet)
    - [Extra JSDoc tags before `@slot`](#extra-jsdoc-tags-before-slot)
    - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
  - [@event](#event)
  - [@ignore / @internal](#ignore--internal)
  - [@deprecated](#deprecated)
  - [@since](#since)
  - [@see](#see)
  - [@link](#link)
  - [@example](#example)
  - [Context API](#context-api)
  - [@restProps](#restprops)
  - [@extendProps](#extendprops)
  - [@template](#template)
  - [@generics](#generics)
  - [@component comments](#component-comments)
  - [Accessor Props](#accessor-props)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Approach

`sveld` statically analyzes exported components and emits docs for consumers. Template parsing runs through sveld's own parser rather than `svelte/compiler`; `svelte/compiler` is imported only for its types, and `svelte/package.json` is read for the installed Svelte version. A differential test (`tests/svelte-template-parse-shim.test.ts`) parses every fixture `.svelte` file with both parsers and asserts the resulting ASTs match, and a weekly `svelte-canary` workflow re-runs that comparison against `svelte@latest` ahead of the lockfile pin.

It extracts:

- props
- slots
- forwarded events
- dispatched events
- context (setContext/getContext)
- `$$restProps`

When inference fails, props fall back to `any` rather than guessing wrong. Authors can tighten types with JSDoc. Comments are optional from the compiler's point of view, so plain JavaScript components still parse.

When both TypeScript syntax and JSDoc are present, `sveld` resolves prop types in this order:

1. explicit TypeScript annotation
2. explicit JSDoc annotation
3. initializer inference
4. `any`

`sveld` stays AST-only. It copies imported and local type text into generated `.d.ts` output but does not run project-wide semantic resolution with the TypeScript compiler. Opaque imported whole-object `$props()` types can therefore stay in declarations without being fully expanded into JSON metadata.

## Features

### `.d.ts` output format (`typesOptions.format`)

`typesOptions.format` controls the shape of generated `.d.ts` files: `"class"` (the default) or `"component"`.

`"class"` extends `SvelteComponentTyped`, deprecated in Svelte 5 and plausibly removed in Svelte 6:

```ts
import { SvelteComponentTyped } from "svelte";

export type ButtonProps = { label?: string };

export default class Button extends SvelteComponentTyped<
  ButtonProps,
  { click: WindowEventMap["click"] },
  { default: Record<string, never> }
> {}
```

`"component"` emits the Svelte 5 `Component` type instead:

```ts
import type { Component } from "svelte";

export type ButtonProps = { label?: string; onclick?: (event: WindowEventMap["click"]) => void };
export type ButtonExports = Record<string, never>;

declare const Button: Component<ButtonProps, ButtonExports, "">;
export default Button;
```

Publish `"component"` if you target Svelte 5+ consumers. `"class"` remains compatible with Svelte 3, 4, and 5.

```ts
await sveld({ types: true, typesOptions: { format: "component" } });
```

Also available as `--types-format=component` on the CLI.

`"component"`'s three type parameters:

- **Props**: the same `$Props`/`<Name>Props` type as `"class"`. Runes components already declare callback props (e.g. `onclick`) as regular props. Legacy (non-runes) components additionally get `on<name>?: (event: Type) => void` callback props for every dispatched and forwarded event, so Svelte 5 consumers can attach handlers as props instead of `on:event`.
- **Exports**: the component's accessor props (exported `function`/`const` members), the same members that render as class members under `"class"`.
- **Bindings**: a union of string literals for props declared with `$bindable(...)` (runes) or marked `@bindable writable` ([see `binding`](#binding)) (legacy) — e.g. `"value"`, or `"value" | "open"` for more than one. `""` when the component declares none, matching Svelte's own convention for "no bindings."

**Generic components.** A `declare const X: Component<...>` value can't itself carry a generic type parameter the way a class can, so generic components (`@template`/`generics`) get a per-component interface instead of `Component<...>` directly:

```ts
interface GenericListComponent {
  new <Item extends { id: string | number } = { id: string }>(
    options: ComponentConstructorOptions<GenericListProps<Item>>,
  ): SvelteComponent<GenericListProps<Item>> & GenericListExports;
  <Item extends { id: string | number } = { id: string }>(
    this: void,
    internals: ComponentInternals,
    props: GenericListProps<Item>,
  ): { $on?(...): () => void; $set?(...): void } & GenericListExports;
  z_$$bindings?: "";
}
declare const GenericList: GenericListComponent;
export default GenericList;
```

Both signatures carry their own generic parameter (not the `const` itself), so `Item` is inferred per usage site, e.g. `<GenericList items={numbers} />` infers `Item` from `numbers`. The `new` signature is the one place `"component"` format still touches a legacy type (`SvelteComponent`/`ComponentConstructorOptions`, not the deprecated `SvelteComponentTyped`): the Svelte language server resolves generic inference for `<Comp prop={...} />` template usage through `new`, not the plain call signature, confirmed by comparing against `@sveltejs/package`'s own generated output for the same component. Omitting it silently breaks inference instead of erroring, so it stays in even though it means one legacy import for generic components.

### Opt-in semantic resolution (`resolveTypes`)

Imported whole-object `$props()` types stay opaque in JSON by default (`"props": []`). Turn on `resolveTypes` when a docs site or prop table needs the individual fields.

```ts
await sveld({ json: true, resolveTypes: true });
```

```svelte
<script lang="ts">
  import type { Props } from "./types";

  let props: Props = $props();
</script>
```

Without `resolveTypes`, JSON lists no props. With it, each field shows up with `"typeSource": "typescript"`:

```jsonc
{
  "props": [
    { "name": "disabled", "type": "boolean", "isRequired": false, "typeSource": "typescript" },
    { "name": "href", "type": "string", "isRequired": true, "typeSource": "typescript" },
    { "name": "variant", "type": "\"primary\" | \"secondary\"", "isRequired": true, "typeSource": "typescript" }
  ]
}
```

**Performance.** Off by default. This is one of the two paths that load TypeScript. It needs `typescript` 7+ and a `tsconfig.json` (see [Requirements](#requirements)); if either is missing, `resolveTypes` fails the run instead of silently producing empty props. It also runs slower than the AST-only pipeline and gets slower as your types grow. Use it only when you need expanded JSON. `.d.ts` output is unchanged.

### Persistent parse cache (`cache`)

Parsed output is written to disk and reused when the source file has not changed, on by default. That applies across runs, including CI on a fresh checkout. Generated `.d.ts` text is cached the same way, but is only reused when the component source _and_ every `typesOptions` value that affects output (for example [`format`](#dts-output-format-typesoptionsformat)) are unchanged; changing any of them regenerates that component's `.d.ts` without invalidating its cached parse.

```ts
await sveld({ json: true });
```

By default this writes to `node_modules/.cache/sveld/parse-cache.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"`, or `cache: false` to disable it. Also available as `--cache` / `--cache=<path>` / `--cache=false` on the CLI.

If a component [`@extendProps`](#extendprops) / [`@extends`](#extendprops) another file, it is re-parsed when that dependency changes, same as in [`watch`](#available-options) mode. Bumping the `sveld` or Svelte version clears the cache.

### Compile-checked `@example` blocks (`checkExamples`)

`@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to check them: plain TS/JS bodies run through the TypeScript program, and `svelte`/`html` bodies run through sveld's own template parser. Broken examples show up as `example-compile-error` (TS/JS) or `example-syntax-error` (markup) diagnostics.

```ts
await sveld({ json: true, checkExamples: true });
```

```svelte
<script>
  /**
   * Formats a value.
   * @param {string} value
   * @returns {string}
   * @example
   * ```js
   * formatValue("ok");
   * ```
   */
  export function formatValue(value) {
    return value;
  }
</script>
```

If `formatValue` is later renamed and the example is never updated, `checkExamples` reports it:

```
@example blocks that failed to compile (1):
  ./Component.svelte
    - Line 1: Cannot find name 'formatValue'.
```

A `svelte`/`html`-fenced example is syntax-checked, not type-checked: sveld parses the markup and discards the AST, so it catches malformed markup (a mismatched closing tag, an unterminated attribute) but not a prop that doesn't exist or a type error inside an expression. Those still need `svelte-check` in the consumer's own tests. Bare unfenced markup (`<Button />` with no code fence) is skipped either way.

```
@example blocks that failed to parse (1):
  ./Component.svelte
    - Line 1: sveld: invalid closing tag </span>.
```

The TS/JS check is narrow on purpose too. It catches renamed or removed symbols and wrong argument counts. Neither path is full type checking, and neither pulls in types sveld cannot see.

The TS/JS path needs `typescript` 7+ and a `tsconfig.json`, same as `resolveTypes` (see [Requirements](#requirements)); missing either fails the run rather than silently skipping every example. The markup path needs neither: pass `checkExamples: "syntax"` to run only it, so a project with only `svelte`/`html` examples (or no `tsconfig.json`) never loads TypeScript. Use `--strict` (or the `strict` option) to fail CI when an example breaks.

### Type inference diagnostics

`sveld` collects unresolved-type diagnostics on every run: props that fall back to `any`, context values typed as `any`, `@event` tags with no dispatch or callback, `$props()`/`{@render}` syntax sveld can't model, and (when `checkExamples` is enabled) `example-compile-error`/`example-syntax-error`. They are always returned from the programmatic `sveld()` API in `SveldResult.diagnostics`. Each diagnostic carries an optional `source` range (the same `{ start: { line, column }, end: { line, column } }` shape as JSON output source ranges) whenever the parser holds a stable position for it.

A prop with no type annotation, no `@type` JSDoc, and no initializer has nothing to infer a type or a default from: its JSON `type` stays absent (`"typeSource": "unknown"`), it triggers a `prop-unknown-type` diagnostic, and the emitted `.d.ts` types it as `any` with no `@default` line (rather than the literal type `undefined`).

With `reportDiagnostics` or `strict`, the grouped summary looks like this:

```
sveld: 5 unresolved types found.

Props without inferred types (1):
  ./icons/Add.svelte
    - Prop "title" type could not be inferred; falling back to "any". (./icons/Add.svelte:4:2) [sveld/prop-unknown-type]

Context values typed as `any` (1):
  ./ThemeProvider.svelte
    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any". (./ThemeProvider.svelte:8:6) [sveld/context-any-type]

@event tags with no dispatch or callback (2):
  ./Modal.svelte
    - @event "open" has no matching dispatch or callback prop. (./Modal.svelte:3:5) [sveld/event-no-source]
    - @event "close" has no matching dispatch or callback prop. (./Modal.svelte:4:5) [sveld/event-no-source]

Component syntax sveld skipped (1):
  ./Tabs.svelte
    - {@render tabs(getTabProps())} argument is not a plain object literal; the render call was not mapped to slot metadata. (./Tabs.svelte:6:4) [sveld/syntax-skipped]
```

When `checkExamples` is also enabled, `@example` failures appear as additional groups: TS/JS failures under `example-compile-error`, `svelte`/`html` failures under `example-syntax-error`.

```
@example blocks that failed to compile (1):
  ./Component.svelte
    - Line 1: Cannot find name 'formatValue'. [sveld/example-compile-error]

@example blocks that failed to parse (1):
  ./Component.svelte
    - Line 1: sveld: invalid closing tag </span>. [sveld/example-syntax-error]
```

By default, nothing is printed. Opt in when you are working on types or want CI output:

```ts
await sveld({ json: true, reportDiagnostics: true });
```

Use `strict: true` (or `--strict`) to exit with code `4` when diagnostics exist. `strict` implies `reportDiagnostics`, so CI always shows why the run failed.

```ts
await sveld({ json: true, strict: true });
```

CLI equivalent:

```sh
npx sveld --json --report-diagnostics
npx sveld --json --strict
```

`--check` is separate: it diffs `COMPONENT_API.json` for API drift and semver classification, not inference warnings.

#### Diagnostic codes

Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongside the older `kind`, so CI config and `diagnostics.ignore` matchers (below) have something that won't shift if the human-readable `message` text changes:

| Code | Severity | Fix |
| --- | --- | --- |
| `sveld/prop-unknown-type` | `warning` | Add a native TypeScript annotation, a `@type` JSDoc tag, or an initializer sveld can infer a type from. |
| `sveld/context-any-type` | `warning` | Annotate the `setContext` value's declaration with `@type` or a native TypeScript type. |
| `sveld/slot-missing-type` | `warning` | Add the required `{Type}` annotation to the `@slot`/`@snippet` tag (e.g. `@slot {{}} name`); until then it falls back to `Record<string, never>`. |
| `sveld/event-no-source` | `warning` | Dispatch the event (`createEventDispatcher`/`dispatch`), forward it (`on:name`), or add a matching `on<Name>` callback prop; otherwise remove the stale `@event` tag. |
| `sveld/example-compile-error` | `error` | Fix the `@example` TS/JS code block so it type-checks, or remove the broken example. |
| `sveld/example-syntax-error` | `error` | Fix the `@example` `svelte`/`html` markup so it parses, or remove the broken example. |
| `sveld/syntax-skipped` | `error` | Rewrite the flagged syntax in a form sveld can model (see the diagnostic's `message` for what was skipped). |
| `sveld/rest-props-unresolved` | `warning` | Spread `$$restProps` onto a plain element (or `svelte:element`) instead of a component, or add an `@restProps` tag to type it manually. |
| `sveld/context-duplicate-key` | `warning` | Remove the duplicate `setContext` call, or give it a distinct key; only the first call's shape is used. |
| `sveld/spread-unresolved` | `warning` | Spread a local object literal or a variable with a resolvable type instead; otherwise the spread widens the generated type to `Record<string, any>`. |
| `sveld/export-unresolved` | `warning` | Export a local declaration directly instead of re-exporting an import or a binding from another file; sveld only resolves exports of a local declaration. |
| `sveld/extend-props-target-missing` | `error` | Point `@extends`/`@extendProps` at a file that exists, and (for a bundled `.svelte` target) name its generated `<Name>Props` interface exactly. |
| `sveld/extend-props-duplicate` | `warning` | Remove the extra `@extends`/`@extendProps` tag; only the last one is used. |
| `sveld/extend-props-override` | `warning` | Rename the own prop, or accept that it intentionally overrides the `@extends` target's prop of the same name. |
| `sveld/jsdoc-unknown-tag` | `warning` | Fix the tag name if it's a typo (e.g. `@depreacted` → `@deprecated`); otherwise no action needed, the tag still passes through unchanged. Only surfaced under `--strict`/`--report-diagnostics`. |
| `sveld/typedef-duplicate` | `warning` | Rename one of the `@typedef`/`@callback` declarations; only the later one is kept. |
| `sveld/property-duplicate` | `warning` | Remove the duplicate `@property`; only the later one is kept. |
| `sveld/generics-conflict` | `warning` | Rename one of the `@generics`/`@template` declarations to a distinct generic name. |
| `sveld/jsdoc-tag-dropped` | `warning` | Move the tag next to a `@slot`/`@snippet`/`@event`/`@typedef`/`@callback` tag in the same comment block so it has something to attach to. |
| `sveld/internal-typedef-referenced` | `error` | Remove `@internal`/`@ignore` from the referenced typedef, or stop referencing it from public type text (inline the shape, or make the referencing item `@internal` too). |
| `sveld/types-inline-unresolved` | `warning` | The import is kept as-is. Point it at a relative `.ts` file that exports a `type`/`interface`, or rename the colliding type. |

#### Severity and `--strict=errors`

Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `jsdoc-tag-dropped`, `types-inline-unresolved` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:

```sh
npx sveld --json --strict=errors
```

```ts
await sveld({ json: true, strict: "errors" });
```

#### Ignoring diagnostics

Two ways to suppress a diagnostic without disabling `strict` for the whole run. Either way, the diagnostic still appears in `SveldResult.diagnostics` (with `ignored: true`) and is still counted in the text summary (`sveld: 2 unresolved types found (1 ignored).`), but never fails `--strict` / `--strict=errors`.

**Config matchers** (`diagnostics.ignore`, an array of `{ code?, component?, name? }`): every field you set on a matcher must match for it to apply; an omitted field matches anything. `component` is a glob (`*` within a path segment, `**` across segments):

```ts
// sveld.config.js
export default defineConfig({
  diagnostics: {
    ignore: [
      // Every prop-unknown-type diagnostic under legacy/.
      { code: "sveld/prop-unknown-type", component: "./legacy/**" },
      // One named symbol, anywhere.
      { name: "internalOnly" },
    ],
  },
});
```

**Inline `@sveld-ignore <code>`**, on the same JSDoc comment as the prop, `@event` tag, or context variable it applies to:

```svelte
<script>
  /**
   * @sveld-ignore sveld/prop-unknown-type
   */
  export let value;
</script>
```

```svelte
<script>
  /**
   * @event {CustomEvent<null>} legacyEvent
   * @sveld-ignore sveld/event-no-source
   */
  export let label;
</script>
```

A bare `@sveld-ignore` (no code) suppresses every diagnostic for that symbol.

## Requirements

- Node 22+ if your config is `sveld.config.js` or `sveld.config.mjs` — `sveld` declares no `engines.node` floor. A `sveld.config.ts` file loads via a raw `import()`, with no transpile step, so it only works if the runtime strips TypeScript itself: on Node this needs unflagged type stripping (Node 22.18 / 23.6+; on older Node 22 patches it's behind `--experimental-strip-types`, so use a `.js`/`.mjs` config instead), which is why Node 24 — the first current major where type stripping is always on — is the only reason to require it. Bun (see `.bun-version`) loads `.ts` configs without Node at all. CI runs on Bun and does not pin a Node version; the release workflow pins Node 24 for `actions/setup-node` on the npm publish job only, not a requirement for consumers.
- `sveld` is ESM-only. `require("sveld")` does not work — use `import` or dynamic `import()`.
- The [persistent parse cache](#persistent-parse-cache-cache) hashes source with `node:crypto`'s one-shot `hash()`, which needs Node 22 (or Bun).
- `sveld` bundles its own template parser to parse `.svelte` files, kept in parity with `svelte/compiler` (see [Approach](#approach)). Parsing does not depend on the Svelte version installed in your project, so Svelte 3 and Svelte 4 codebases parse the same way Svelte 5 codebases do — there is no compiler version to match up.
- [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes), [`checkExamples`](#compile-checked-example-blocks-checkexamples), and [`typesOptions.inline: "all"`](#typesoptionsinline) are optional and need `typescript` 7 or later (which provides `typescript/unstable/async`) plus a `tsconfig.json`. Everything else, including `.d.ts` generation and `typesOptions.inline: "local"`, is AST-only and never loads TypeScript. If any of the three is enabled and TypeScript can't be started (missing, too old, or no `tsconfig.json`), the run fails loudly: `sveld()` throws and the CLI exits `2` naming the requirement, rather than silently skipping the check. For `typesOptions.inline: "all"` this only actually triggers when there's a non-allow-listed bare import somewhere in the bundle to resolve; see [`typesOptions.inline`](#typesoptionsinline).

## Usage

### Installation

Install `sveld` as a development dependency.

```sh
# npm
npm i -D sveld

# pnpm
pnpm i -D sveld

# Bun
bun i -D sveld

# Yarn
yarn add -D sveld
```

### Vite

Import and add `sveld` as a plugin to your `vite.config.ts`. The plugin only runs during `vite build`, unless `watch: true` is set, in which case it also regenerates output during `vite dev`.

```ts
// vite.config.ts
import { svelte } from "@sveltejs/vite-plugin-svelte";
import sveld from "sveld";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [svelte(), sveld()],
});
```

Since Vite uses Rollup for production builds, the same plugin works in Rollup configs.

Unlike the CLI and the programmatic `sveld()` API, the plugin ignores `sveld.config.*` by default: pass `config: true` to load it and merge it with the options given here (these take precedence over the same key in the file), or a string to point at a specific config file.

```ts
sveld({
  config: true,
  json: true, // wins over `json` set in sveld.config.*
});
```

By default, `sveld` uses the `"svelte"` field from your `package.json` to determine the entry point. You can override this by specifying an explicit `entry` option:

```js
sveld({
  entry: "src/index.js",
});
```

When building the library, TypeScript definitions are emitted to the `types` folder by default.

Customize the output folder using the `typesOptions.outDir` option.

The following example emits the output to the `dist` folder:

```diff
sveld({
+  typesOptions: {
+    outDir: 'dist',
+  }
})
```

### CLI

The CLI uses the `"svelte"` field from your `package.json` as the entry point:

```sh
npx sveld
```

Generate documentation in JSON and/or Markdown formats using the following flags:

```sh
npx sveld --json --markdown
```

If no entry point can be resolved (no `package.json#svelte` field and no `--entry`), the CLI exits `1` and prints the reason to `stderr`. If `src/index.js` happens to exist relative to your working directory, sveld falls back to it and prints a one-line note asking you to set `package.json#svelte` (or `--entry`) instead of relying on the fallback.

Flags are kebab-case: `--entry`, `--glob`, `--types`, `--json`, `--markdown`, `--custom-elements`, `--llms`, `--fail-fast`, `--dry-run`, `--cache`, `--resolve-types`, `--check-examples`, `--report-diagnostics`, `--strict`, `--check`, `--check-level`, `--types-format`, `--types-export`, `--types-comments`, `--types-inline`, `--types-index-types`, `--types-props-declaration`, `--quiet`, `--stdout`, `--format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. `--entry`, `--cache`, `--check`, `--types-format`, `--types-export`, `--types-comments`, `--types-inline`, and `--types-props-declaration` take their value either as `--flag=value` or as a separate `--flag value` argument (`sveld --entry src/index.js` and `sveld --entry=src/index.js` are equivalent); if the next argument starts with `--` it's not consumed as a value, so `--cache` and `--check` fall back to their default location and the rest of that list report a usage error naming the flag. Boolean flags (`--json`, `--glob`, `--strict`, `--types-index-types`, and the like) never consume a following argument. An unrecognized flag (e.g. `--markdwon`) prints `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Unknown flag: --markdwon Did you mean --markdown?`. sveld takes no positional arguments, so any non-flag argument errors the same way.

Writer progress lines (`created "..."` / `unchanged "..."`) print to `stderr`, keeping `stdout` reserved for machine-readable data. Pass `--quiet` (or `quiet: true` in `sveld.config.*`) to suppress them; it does not suppress error messages, the diagnostics summary (`--report-diagnostics` / `--strict`), or the `--check` report.

Pass `--dry-run` to resolve the entry, load config, and parse components through the real pipeline (so parse errors, diagnostics, `--strict`, and `--check` all behave as in a real run), then print `would write "<path>"` to `stdout` for each output file instead of writing it, e.g. `sveld --json --markdown --dry-run`. Nothing is written, including the parse cache. `--check` never writes regardless of `--dry-run`, since it only diffs against the committed snapshot.

Pass `--stdout` alongside exactly one of `--json`, `--markdown`, or `--custom-elements` to print that single document to `stdout` instead of writing it to disk, e.g. `sveld --json --stdout | jq '.components[].moduleName'`. Zero or more than one of those three flags, `--types`, or `--check` combined with `--stdout` is a usage error that prints to `stderr` and exits `1` without generating anything; the default `.d.ts` generation is skipped in `--stdout` mode since type definitions span multiple files.

`--stdout=ndjson` (only valid with `--json`) prints one minified JSON object per exported component per line instead of the single combined document, in the same order as the combined document's `components` array, e.g. `sveld --json --stdout=ndjson | jq -c 'select(.props | length > 0)'`. Lines are only written after the run completes (component records are only final after cross-component resolution), so this is a line-oriented serialization format, not incremental streaming. Bare `--stdout` (or `--stdout=json`) keeps the single-document behavior; any other value is a usage error.

`--format=json` switches the `--check` report and the `--report-diagnostics` / `--strict` diagnostics summary from prose to JSON, so scripts and agents don't have to regex the text output, e.g. `sveld --json --check --format=json | jq '.bump'`. Channels are unchanged: the check report prints to `stdout` and the diagnostics summary to `stderr`, same as the text format. Each envelope (`{ kind: "check-report", schemaVersion: 1, ... }` / `{ kind: "diagnostics", schemaVersion: 1, diagnostics: [...] }`) carries its own `schemaVersion`, bumped independently of `COMPONENT_API.json`'s if either shape ever changes incompatibly. The default remains `--format=text`; an unrecognized value (e.g. `--format=yaml`) is a usage error that prints to `stderr` and exits `1` without generating anything.

`--format=github` prints [GitHub Actions workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) instead: `::warning`/`::error` for each diagnostic (by `severity`) and `::error` for each `--check` change that meets `--check-level` (`major` by default), annotating the offending line directly in the PR's "Files changed" tab. Ignored diagnostics and changes below `--check-level` produce no annotation. When the `GITHUB_STEP_SUMMARY` env var is set (GitHub Actions sets it automatically), sveld also appends a Markdown table mirroring the same rows to that file, so the job summary shows them even for someone not reviewing the diff. A minimal workflow step:

```yaml
- run: npx sveld --json --check --report-diagnostics --strict=errors --format=github
```

Run `npx sveld --help` for the full flag list with descriptions, or `npx sveld --version` to print the installed version.

Pass `--glob` with a directory as `--entry` (no barrel file) to document every `.svelte` file under it directly, with no re-export needed: each component's sanitized filename becomes its module name in JSON, Markdown, and the generated `index.d.ts`, in addition to the per-component `.d.ts` every `--glob` run already produces. This is the same set `mergeGlobbedComponents` discovers when `--glob` is combined with a file entry; a directory entry just has no barrel to layer it onto.

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Usage or configuration error (unknown flag, bad flag value, unresolvable entry, unresolved re-export or path alias) |
| `2` | Generation failure (a component failed to parse under `--fail-fast`, or an unrecoverable pipeline error) |
| `3` | Breaking API change detected by `--check` |
| `4` | Diagnostics present under `--strict` |

Every failure is still reported to its usual channel even when more than one applies in a single run (e.g. a breaking change under `--check` alongside diagnostics under `--strict`); the process exits with the lowest applicable code. All failure codes are nonzero, so existing `if sveld; then ...` and `set -e` scripts that only check for success keep working unmodified.

### CI: API-drift checks (`--check`)

`--check` diffs the parsed component API against a committed `COMPONENT_API.json` snapshot, assigns a semver bump to each change, and exits `3` when it finds a breaking change.

1. Generate and commit the snapshot once: `npx sveld --json`, then commit `COMPONENT_API.json`.
2. Add `npx sveld --check` to CI:

```sh
npx sveld --check
```

```
sveld --check: 2 API changes detected against "COMPONENT_API.json".
Suggested semver bump: major.

  Button
    [BREAKING] prop "target" added (required)
    [BREAKING] prop "href" removed
```

| Change | Bump |
| --- | --- |
| Component added | `minor` |
| Component removed | `major` |
| Prop/export added (optional) | `minor` |
| Prop/export added (required) | `major` |
| Prop/export removed | `major` |
| Prop/export became required | `major` |
| Prop/export became optional | `minor` |
| Prop/export type widened (union gained a member) | `minor` |
| Prop/export type narrowed (union lost a member) | `major` |
| Prop/export type changed (anything else) | `major` |
| Function-typed prop/export gained a trailing optional param | `minor` |
| Function-typed prop/export lost a param, or return type changed | `major` |
| Prop gained a writable binding (`bind:`-able) | `minor` |
| Prop lost a writable binding | `major` |
| Prop/export default value changed (type unchanged) | `patch` |
| `@deprecated` added | `minor` |
| `@deprecated` removed | `patch` |
| `constant`/`reactive` flag flipped | `minor` |
| Event/slot added | `minor` |
| Event/slot removed | `major` |
| Event detail / slot props type widened | `minor` |
| Event detail / slot props type narrowed or otherwise changed | `major` |
| `generics`, `@restProps`, `@extends`, or context shape changed | `major` (not classified further) |
| Description-only change | not reported |

`--check` does not write the snapshot. Run `sveld --json` (or `sveld --json --check`) and commit the file when you want to update it. If there is no snapshot yet, `--check` prints a notice and exits `0`.

Use `--check=<path>` to diff against a snapshot at a custom location (defaults to `jsonOptions.outFile`, or `COMPONENT_API.json`).

By default `--check` only fails the run (exit `3`) on a `major` bump; `minor` and `patch` changes are still reported but don't fail CI. Pass `--check-level=minor` or `--check-level=patch` to fail the run at a lower threshold, e.g. to gate a package that promises no additive changes without a minor release.

If the committed snapshot's `schemaVersion` doesn't match the version `sveld` currently emits, `--check` reports a `kind: "schema"` entry instead of diffing (a version mismatch isn't a semver bump) and exits `1` (usage error): regenerate the snapshot with `sveld --json`.

The CLI exits non-zero on any fatal error (an unreadable entry, a config file that throws, etc.), not just on `--strict`/`--check` findings, so it's safe to use either flag as a CI gate. See [Exit codes](#exit-codes) for how these are differentiated.

Pass `--format=json` for a machine-readable report on `stdout` instead of the prose above, e.g. `sveld --check --format=json | jq '.bump'` or `sveld --check --format=json | jq '.changes[] | select(.bump == "major")'`.

### CI: strictness profiles (`--strict=ci`/`--strict=local`)

CI and local runs usually want a different bundle of `strict`, `reportDiagnostics`, `check`, and `checkExamples` flags, previously assembled by hand. `--strict=ci`/`strict: "ci"` and `--strict=local`/`strict: "local"` are shorthands for two common bundles. Bare `--strict`/`strict: true` (and `--strict=errors`) are unchanged.

`--strict=ci` expands to `{ strict: true, reportDiagnostics: true, check: true, checkExamples: true }` — the full gate for a CI job:

```sh
npx sveld --json --strict=ci
```

`--strict=local` expands to `{ reportDiagnostics: true }` — diagnostics printed for a developer to see, without failing the command or requiring a committed `COMPONENT_API.json` snapshot:

```sh
npx sveld --json --strict=local
```

The profile's keys are applied first, then any other key set alongside `strict` overrides it, so you can opt back out of one piece:

```ts
// Everything --strict=ci implies, except the TypeScript-checked half of checkExamples.
await sveld({ json: true, strict: "ci", checkExamples: "syntax" });
```

### Node.js

You can also call `sveld` from Node.js. See [Requirements](#requirements) for supported Node versions and the ESM-only constraint.

If no `entry` is specified, `sveld` infers the entry point based on the `package.json#svelte` field. If no entry point can be resolved, `sveld()` throws with an actionable message (previously it resolved to `{ diagnostics: [] }` and generated nothing).

> `input` was renamed to `entry` to match the CLI, plugin, and config. Calls passing `input` throw with a message pointing at `entry`.

```js
import { sveld } from "sveld";
import pkg from "./package.json" with { type: "json" };

const { diagnostics } = await sveld({
  entry: "./src/index.js",
  glob: true,
  markdown: true,
  markdownOptions: {
    onAppend: (type, document, components) => {
      if (type === "h1")
        document.append(
          "quote",
          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
        );
    },
  },
  json: true,
  jsonOptions: {
    outFile: "docs/src/COMPONENT_API.json",
  },
});
```

`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)). `errors` is always populated too: components that failed to parse, whether or not `failFast` is set.

Pass `check: true` (or `check: "<path>"` for a custom snapshot location) to diff against a committed `COMPONENT_API.json`, the same way `--check` does on the CLI. The result lands on `SveldResult.check`. `sveld()` never touches `process.exitCode` itself; it returns a suggested `exitCode` (`0`, `3` for a breaking `check` result, or `4` for `strict` diagnostics — the same mapping the CLI uses, `3` winning over `4`) so you can assign it yourself:

```js
import { formatCheckReport } from "sveld";

const { check, exitCode } = await sveld({ json: true, check: true });

if (check) {
  console.log(formatCheckReport(check));
}

process.exitCode = exitCode;
```

See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check) for how changes are classified.

#### `jsonOptions.outDir`

With `json: true`, `sveld` writes `COMPONENT_API.json` at the project root. The file documents all components.

Use the `jsonOptions.outDir` option to specify the folder for individual JSON files to be emitted.

```js
sveld({
  json: true,
  jsonOptions: {
    // an individual JSON file will be generated for each component API
    // e.g. "docs/Button.api.json"
    outDir: "docs",
  },
});
```

#### `jsonOptions.source`

Every prop, slot, event, typedef, and context in `COMPONENT_API.json` carries a `source` position range (plus `componentCommentSource` on the component itself) when the parser has a stable AST position for it. For a large component library this is a substantial share of the file — roughly a quarter of `COMPONENT_API.json` for a 150+ component library — and many consumers (docs sites, LLM context) never read it.

Set `jsonOptions.source` to `false` to omit every `source`/`componentCommentSource` range and shrink the file:

```js
sveld({
  json: true,
  jsonOptions: {
    source: false,
  },
});
```

`source: true` is the default; every other field is unaffected. `EntryExport.source` (the declaring module's relative path, from `documentExports`) is a different field with a string value and is never stripped.

### Browser

`sveld/browser` is a Node-free subpath export for running `sveld` client-side — e.g. an in-browser Svelte playground or REPL that parses whatever `.svelte` source the user typed and renders docs for it live. It bundles with Vite, esbuild, webpack, or Rollup without a `node:fs`/`node:path` polyfill.

It covers parsing one component's source and rendering that result to any output format `sveld` supports (JSON, Markdown, `.d.ts`, Custom Elements Manifest). It does not cover project-wide glob scanning, the config file, or the CLI/Vite plugin (`sveld()`/`pluginSveld()`) — those walk the filesystem and only make sense in Node. Use the main `sveld` entry point for those.

```ts
import {
  asNormalizedPath,
  ComponentParser,
  buildComponentApiDocument,
  writeMarkdownCore,
  writeTsDefinition,
  buildCustomElementsManifest,
} from "sveld/browser";

const parser = new ComponentParser();
const moduleName = "Button";
const filePath = "Button.svelte";
const parsed = parser.parseSvelteComponent(source, { moduleName, filePath });

// `parseSvelteComponent` returns component metadata only; add `moduleName`
// and `filePath` yourself to match the `ComponentDocApi` shape the writers expect.
const component = { ...parsed, moduleName, filePath: asNormalizedPath(filePath) };
const components = new Map([[moduleName, component]]);

// JSON
const jsonDoc = buildComponentApiDocument(components);

// Markdown
const markdown = writeMarkdownCore(components);

// TypeScript definitions (per component)
const dts = writeTsDefinition(jsonDoc.components[0]);

// Custom Elements Manifest
const cem = buildCustomElementsManifest(components, {
  resolveModulePath: (component) => component.filePath,
});
```

`ComponentParser` is stateful but reusable across parses — call `parseSvelteComponent` again on the same instance for the next component instead of constructing a new one each time.

See [`playground/`](playground) in this repo for a working example: it parses Svelte source typed into an editor and renders JSON, Markdown, TypeScript, and Custom Elements Manifest tabs, all client-side. Deployed at [sveld.onrender.com](https://sveld.onrender.com).

### Config File

Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API. The Vite/Rollup plugin ignores it unless you opt in with the [`config`](#vite) option.

Import `defineConfig` from `sveld` for typed options. Config files must use ESM syntax (`export default`).

```js
// sveld.config.js
import { defineConfig } from "sveld";

export default defineConfig({
  glob: true,
  json: true,
  markdown: true,
});
```

Later sources win when options overlap:

CLI flags > config file > `package.json#svelte` inference / defaults

With the config above, `npx sveld --json` keeps `glob` and `markdown` from the file. A CLI flag overrides the same key in the config.

`strict`, `reportDiagnostics`, and `check` are valid config keys too — not just CLI flags or `sveld()` options — and follow the same precedence: a CLI flag (or an option passed to `sveld()`) overrides the same key set in the config file.

```js
// sveld.config.js
export default {
  json: true,
  strict: true,
  check: "snapshots/COMPONENT_API.json",
};
```

Merging is one level deep for object-valued options (`typesOptions`, `jsonOptions`, `markdownOptions`, `customElementsOptions`, `additionalWriters`): setting one nested key at the CLI or in `sveld()` doesn't drop sibling keys set in the config file. Arrays and functions (e.g. `markdownOptions.onAppend`) are replaced outright, never merged.

```js
// sveld.config.js
export default {
  typesOptions: { outDir: "dist", preamble: "// license" },
};
```

`npx sveld --types-format=component` keeps `outDir` and `preamble` from the file and adds `format: "component"`, rather than replacing `typesOptions` entirely.

An unrecognized option key (top-level, or inside a `*Options` object) is not an error: it prints a `console.warn` naming the key, with a "did you mean" suggestion when a known key is close enough.

A bad config (syntax error, throws at load time, or no default-export object) fails with an error that names the file.

### Publishing to NPM

TypeScript definitions land in the `types` folder by default. Point consumers at them with an `exports` map, and include that folder in `package.json` when you publish to npm.

```diff
{
  "svelte": "./src/index.js",
+ "exports": {
+   ".": {
+     "types": "./types/index.d.ts",
+     "svelte": "./src/index.js",
+     "default": "./lib/index.mjs"
+   }
+ },
  "main": "./lib/index.mjs",
  "files": [
    "src",
    "lib",
+   "types",
  ]
}
```

The `svelte` condition lets bundlers that understand it (Vite, Rollup, webpack via `svelte-loader`) resolve straight to source; `types` and `default` cover TypeScript and everything else. Keep the top-level `"svelte"` field too — older tooling that predates conditional exports still reads it directly.

## Available Options

### Plugin Options

- **`entry`** (string, optional): Specify the entry point to uncompiled Svelte source. If not provided, sveld uses the `"svelte"` field from `package.json`.
- **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
- **`documentExports`** (boolean, optional): Include consts, functions, and types from the entry barrel in JSON (`exports`) and Markdown ("Exports"). Off by default. See [Documenting Entry Exports](#documenting-entry-exports).
- **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
- **`typesOptions`** (object, optional): Options for TypeScript definition generation.
  - **`outDir`** (string, optional, default: `"types"`): Output directory for generated `.d.ts` files, relative to the project root.
  - **`preamble`** (string, optional, default: `""`): Raw text prepended to the top of the generated `index.d.ts` barrel file, before the `export * from "./..."` lines. Useful for license headers or lint-disable comments. See [`typesOptions.preamble`](#typesoptionspreamble) below.
  - **`format`** (`"class"` | `"component"`, optional, default: `"class"`): `.d.ts` output shape. `"class"` extends `SvelteComponentTyped`; `"component"` emits the Svelte 5 `Component` type. Also available as `--types-format`. See [`.d.ts` output format](#dts-output-format-typesoptionsformat).
  - **`exportTypes`** (`boolean | { props?, exports?, typedefs?, contexts? }`, optional, default: `true`): Which generated type declarations get an `export` keyword. `false` keeps them all local to the `.d.ts` file; an object picks per kind. Also available as `--types-export=<all|none>` (the CLI can only set the boolean form, not the per-kind object). See [`typesOptions.exportTypes`](#typesoptionsexporttypes).
  - **`typeNames`** (`{ props?: string; exports?: string }`, optional, default: `{ props: "{name}Props", exports: "{name}Exports" }`): Templates for generated type names. No CLI flag; config file or `sveld()` only. See [`typesOptions.typeNames`](#typesoptionstypenames).
  - **`comments`** (`"all" | "descriptions" | "none"`, optional, default: `"all"`): How much JSDoc lands in the generated `.d.ts`. `"all"` keeps descriptions, `@deprecated`, `@default`, and passthrough tags (`@since`, `@see`, `@example`, `@link`); `"descriptions"` keeps descriptions and `@deprecated` only; `"none"` emits no comments at all. Also available as `--types-comments=<all|descriptions|none>`. See [`typesOptions.comments`](#typesoptionscomments).
  - **`propsDeclaration`** (`"type" | "interface"`, optional, default: `"type"`): `"interface"` emits the props type as an `interface` instead of a `type` alias when the props are a plain object. Also available as `--types-props-declaration=<type|interface>`. See [`typesOptions.propsDeclaration`](#typesoptionspropsdeclaration).
  - **`transform`** (function, optional): Post-processes each generated file's text before it is written. Runs after the generated-text cache, so it applies on every run. No CLI flag; config file or `sveld()` only. See [`typesOptions.transform`](#typesoptionstransform).
  - **`indexTypes`** (`boolean | { props?, exports?, typedefs?, contexts? }`, optional, default: `false`): Also re-export generated types from `index.d.ts`. `true` re-exports each component's `Props` type (and `Exports` under `format: "component"`); an object can additionally include typedefs and contexts. Also available as `--types-index-types` (the CLI can only set the boolean form, not the per-kind object). See [`typesOptions.indexTypes`](#typesoptionsindextypes).
  - **`inline`** (`false | "local" | "all"`, optional, default: `false`): Copies `type`/`interface` declarations imported from a relative source (or a tsconfig/jsconfig path alias) directly into the `.d.ts`, dropping the import. Also available as `--types-inline=<local|all>` (`--types-inline=false` resets to the default). See [`typesOptions.inline`](#typesoptionsinline).
- **`json`** (boolean, optional): Generate component documentation in JSON format.
- **`jsonOptions`** (object, optional): Options for JSON output.
  - **`outFile`** (string, optional, default: `"COMPONENT_API.json"`): Path (relative to the project root) for the single combined JSON document. Ignored when `outDir` is set.
  - **`outDir`** (string, optional): Emit one JSON file per component (`<ComponentName>.api.json`) into this directory instead of a single combined file. See [`jsonOptions.outDir`](#jsonoptionsoutdir).
  - **`source`** (boolean, optional, default: `true`): Set to `false` to omit every `source`/`componentCommentSource` position range from the output. See [`jsonOptions.source`](#jsonoptionssource).
- **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
- **`markdownOptions`** (object, optional): Options for Markdown output.
  - **`outFile`** (string, optional, default: `"COMPONENT_INDEX.md"`): Path (relative to the project root) for the single combined Markdown document. Ignored when `outDir` is set.
  - **`outDir`** (string, optional): Emit one `<ModuleName>.md` file per component into this directory, plus an index `README.md` linking to each, instead of a single combined file. See [`markdownOptions.outDir`](#markdownoptionsoutdir).
  - **`write`** (boolean, optional, default: `true`): Set to `false` to skip writing to disk — the rendered combined document is still returned, or (with `outDir` set) no files are written at all.
  - **`onAppend`** (function, optional): Callback invoked every time a heading, quote, paragraph, divider, or raw block is appended to the document. Lets you inject extra content, e.g. a summary line under the title. See [`markdownOptions.onAppend`](#markdownoptionsonappend) below.
- **`customElements`** (boolean, optional): Generate a [Custom Elements Manifest](#custom-elements-manifest) (`custom-elements.json`). Also available as the `--custom-elements` CLI flag.
- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output.
  - **`outFile`** (string, optional, default: `"custom-elements.json"`): Path (relative to the project root) for the generated manifest file.
- **`llms`** (boolean, optional): Generate an [`llms.txt` / `llms-full.txt`](#llmstxt-output) pair. Also available as the `--llms` CLI flag.
- **`llmsOptions`** (object, optional): Options for `llms.txt` / `llms-full.txt` output.
  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`.
  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title.
- **`config`** (boolean | string, optional, default: `false`): Load `sveld.config.{js,mjs,ts}` and merge it with these options; these options win when a key is set in both. `true` resolves the config from the Vite project root (or `process.cwd()` outside Vite); a string is an explicit path to the config file. See [Config File](#config-file).
- **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when relevant source changes during `vite dev` / `vite build --watch`. A reparse is triggered by: editing a component; editing the entry barrel itself, which adds/removes the corresponding component; or editing a non-`.svelte` file a component depends on via [`@extendProps`](#extendprops) / `@extends` or a typedef `import("./x")` reference. Only the affected components are re-parsed, rather than rebuilding every component. Overlapping regenerations are queued, never run concurrently. Without this option, the plugin only runs during `vite build`.
- **`failFast`** (boolean, optional, default: `false`): Abort the entire run when a single component fails to parse. By default, parse failures are collected as diagnostics (and reported to `stderr`) so the remaining components still emit their output. Also available as the `--fail-fast` CLI flag.
- **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. Also available as `--resolve-types` (`--resolveTypes` remains as a deprecated alias). See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
- **`cache`** (boolean | string, optional, default: `true`): Write parsed component output to disk and skip re-parsing unchanged files on later runs. On by default, writing to `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path; pass `false` to disable. Also available as `--cache` / `--cache=<path>` / `--cache=false`. See [Persistent parse cache](#persistent-parse-cache-cache).
- **`checkExamples`** (`boolean | "syntax"`, optional, default: `false`): `true` runs plain TS/JS `@example` blocks through the TypeScript program (`example-compile-error` diagnostics) and `svelte`/`html` blocks through sveld's own template parser (`example-syntax-error` diagnostics). `"syntax"` runs only the markup path, so `typescript` is never loaded. Also available as `--check-examples` / `--check-examples=syntax` (`--checkExamples` remains as a deprecated alias). See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
- **`reportDiagnostics`** (boolean, optional, default: `false`): Print unresolved-type diagnostics to stderr (CLI) or `console.warn` (programmatic API). Also available as `--report-diagnostics`. See [Type inference diagnostics](#type-inference-diagnostics).
- **`strict`** (`boolean | "errors" | "ci" | "local"`, optional, default: `false`): Exit with code `4` when diagnostics exist. Implies `reportDiagnostics`. `"errors"` fails only on `severity: "error"` diagnostics, letting `warning` ones through. `"ci"` and `"local"` are strictness profiles that expand into other options before this object's own keys are applied. Also available as `--strict` / `--strict=errors` / `--strict=ci` / `--strict=local`. See [Type inference diagnostics](#type-inference-diagnostics) and [CI: strictness profiles](#ci-strictness-profiles---strictci---strictlocal).
- **`diagnostics.ignore`** (`Array<{ code?: string; component?: string; name?: string }>`, optional): Marks matching diagnostics `ignored` — they're still reported and counted, but never fail `strict`. `component` is a glob; an omitted field on a matcher matches anything. No CLI flag; config-file or `sveld()` only. See [Ignoring diagnostics](#ignoring-diagnostics).
- **`check`** (boolean | string, optional, default: `false`): Diff the parsed component API against a committed snapshot and assign a semver bump to each change. `true` uses the `json` writer's `outFile` (or `COMPONENT_API.json`); a string sets a custom snapshot path. Also available as `--check` / `--check=<path>`. On the CLI this exits `3` on a breaking change; from `sveld()` it's returned on `SveldResult.check` for you to act on. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
- **`checkLevel`** (`"major" | "minor" | "patch"`, optional, default: `"major"`): Minimum bump `--check` fails the CLI run on. Also available as `--check-level`. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
- **`quiet`** (boolean, optional, default: `false`): Suppress writer progress logs (`created "..."` / `unchanged "..."`), which print to `stderr` by default. Does not suppress error messages, the diagnostics summary, or the `--check` report. Also available as `--quiet`.
- **`dryRun`** (boolean, optional, default: `false`): Resolve the entry, load config, and parse components through the real pipeline, then print `would write "<path>"` to `stdout` for each output file instead of writing it, including the parse cache. Diagnostics, `strict`, and `check` behave as in a real run. CLI-only via `--dry-run`; the Vite plugin does not expose this option.

By default, only TypeScript definitions are generated.

To generate documentation in Markdown and JSON formats, set `markdown` and `json` to `true`.

```diff
sveld({
+  markdown: true,
+  json: true,
})
```

#### `typesOptions.preamble`

Use `typesOptions.preamble` to prepend raw text to the generated `types/index.d.ts` barrel file — for example, a license header that should ship with every published `.d.ts` file.

```js
sveld({
  types: true,
  typesOptions: {
    preamble: "// Copyright (c) 2026 Acme Inc. All rights reserved.\n\n",
  },
});
```

```ts
// types/index.d.ts
// Copyright (c) 2026 Acme Inc. All rights reserved.

export { default as Button } from "./Button.svelte";
```

`preamble` only affects the barrel file (`index.d.ts`); per-component `.d.ts` files are untouched.

#### `typesOptions.exportTypes`

Every type sveld generates is `export`ed by default. `typesOptions.exportTypes` lets a library keep some or all of them local to each component's `.d.ts` — useful when the props type is an implementation detail, or when it collides with a hand-written type of the same name in the package's own `index.d.ts`. Only the component itself needs to be public either way.

```js
sveld({
  types: true,
  typesOptions: {
    exportTypes: false,
  },
});
```

**Button.svelte.d.ts** before:

```ts
export type ButtonProps = { label?: string };

export default class Button extends SvelteComponentTyped<
  ButtonProps,
  { click: WindowEventMap["click"] },
  { default: Record<string, never> }
> {}
```

**Button.svelte.d.ts** after (`exportTypes: false`):

```ts
type ButtonProps = { label?: string };

export default class Button extends SvelteComponentTyped<
  ButtonProps,
  { click: WindowEventMap["click"] },
  { default: Record<string, never> }
> {}
```

`Button` is still the only thing a consumer imports; `ButtonProps` is just no longer part of the public surface (it can still be referenced structurally — through `ComponentProps<typeof Button>`, for instance).

Pass an object instead of a boolean to pick per kind:

```js
typesOptions: {
  exportTypes: {
    props: false,   // export type <Name>Props
    exports: true,  // export type <Name>Exports (format: "component" only)
    typedefs: true, // export interface|type <Typedef> from @typedef
    contexts: true, // export type <Context> from setContext
  },
}
```

Any key left out defaults to `true`.

`<script context="module">` exports (`export declare const` / `export declare function`) are real runtime exports and are always emitted as exports, regardless of `exportTypes`.

One exception: when a bundled component uses [`@extendProps`](#extendprops) to extend another bundled component, sveld emits `import type { ButtonProps } from "./Button.svelte"` in the extending component's `.d.ts`. If `Button`'s props type stopped being exported, that import would break — so sveld always keeps a component's props type exported when another component in the same run extends it, even under `exportTypes: false`.

Also available as `--types-export=<all|none>` on the CLI, mapped to the boolean form (`all` => `true`, `none` => `false`) — the CLI can't express the per-kind object form.

#### `typesOptions.typeNames`

By default, sveld names the generated props type `<Name>Props` and (for [`format: "component"`](#dts-output-format-typesoptionsformat)) the exports type `<Name>Exports`, where `<Name>` is the component's module name. `typesOptions.typeNames` lets a library follow its own naming convention instead, via a `{name}` placeholder template.

```js
sveld({
  types: true,
  typesOptions: {
    typeNames: { props: "I{name}Props" },
  },
});
```

**Button.svelte.d.ts** before / after:

```diff
- export type ButtonProps = { label?: string };
+ export type IButtonProps = { label?: string };

- export default class Button extends SvelteComponentTyped<ButtonProps, ...> {}
+ export default class Button extends SvelteComponentTyped<IButtonProps, ...> {}
```

Each template must contain `{name}` and produce a valid identifier once substituted; sveld throws otherwise. Any key left out of the object keeps its default (`"{name}Props"` / `"{name}Exports"`).

If a bundled component then [`@extendProps`](#extendprops)/`@extends`-es another one, the tag must name the *templated* interface — `@extendProps {"./Button.svelte"} IButtonProps`, not `ButtonProps` — or sveld reports [`extend-props-target-missing`](#type-inference-diagnostics).

There's no CLI flag for `typeNames`; set it via a config file or the programmatic `sveld()` API.

#### `typesOptions.comments`

By default sveld carries every prop's JSDoc into the generated `.d.ts`: the description, `@deprecated`, `@default`, and passthrough tags like `@since`. `typesOptions.comments` lets a library ship a leaner `.d.ts` instead — useful when the docs live elsewhere (a docs site, Storybook) and duplicating them in the type declaration just adds noise.

```svelte
<script>
  /**
   * The button's visible label.
   * @deprecated Use `text` instead.
   * @default ""
   * @since 1.2.0
   */
  export let label = "";
</script>
```

**`comments: "all"`** (default) — description, `@deprecated`, `@default`, and passthrough tags:

```ts
/**
 * The button's visible label.
 * @deprecated Use `text` instead.
 * @default ""
 * @since 1.2.0
 */
label?: string;
```

**`comments: "descriptions"`** — description and `@deprecated` only; `@default` and passthrough tags are dropped:

```ts
/**
 * The button's visible label.
 * @deprecated Use `text` instead.
 */
label?: string;
```

`@deprecated` survives at this level on purpose: editors render a strikethrough from it, so it's API information a consumer needs, not documentation.

**`comments: "none"`** — no comments at all; only the declaration:

```ts
label?: string;
```

```js
sveld({
  types: true,
  typesOptions: {
    comments: "descriptions",
  },
});
```

`@internal`/`@ignore` members are removed from every output regardless of this option — see [`@ignore` / `@internal`](#ignore--internal). `comments` only controls how much JSDoc survives for members that *do* get emitted.

Also available as `--types-comments=<all|descriptions|none>` on the CLI.

#### `typesOptions.propsDeclaration`

By default sveld emits the props type as a `type` alias. `typesOptions.propsDeclaration: "interface"` emits an `interface` instead, for consumers who want to extend it with `interface MyProps extends ButtonProps`, rely on declaration merging, or just prefer the shorter editor hover an `interface` gets.

```js
sveld({
  types: true,
  typesOptions: {
    propsDeclaration: "interface",
  },
});
```

**Button.svelte.d.ts** before / after:

```diff
- export type ButtonProps = { label?: string };
+ export interface ButtonProps { label?: string }
```

Only a plain object props type can become an `interface` safely. These shapes are intersections instead, and always stay a `type` alias regardless of this option:

- a component with [`@restProps`](#restprops) (`Omit<$RestProps, keyof $Props> & $Props`)
- a component with [`@extendProps`](#extendprops) (`Omit<Extended, keyof $Props> & $Props`)
- a component with a whole-object `$props()` type resolved via [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes) (`CanonicalPropsType & { ... }`)
- a component with no props at all (`Record<string, never>`; an empty `interface` trips `noEmptyInterface` in consumer lint setups)

Also available as `--types-props-declaration=<type|interface>` on the CLI.

#### `typesOptions.transform`

`typesOptions.transform` is an escape hatch for one-off edits no other option covers - appending a `/// <reference>` directive, rewriting an import specifier for a monorepo, stripping a banner. It runs on every generated `.d.ts` file's text, immediately before it's written, and receives the block's `kind` (`"component"` or `"index"`), and for `"component"` the parsed `ComponentDocApi` too, plus the output `filePath` relative to `outDir` (e.g. `"Button.svelte.d.ts"` or `"index.d.ts"`). Return the new text, synchronously or via a `Promise`.

```js
sveld({
  types: true,
  typesOptions: {
    transform: (text, context) => {
      if (context.kind !== "component") return text;
      return `/// <reference types="svelte" />\n${text}`;
    },
  },
});
```

```ts
// Button.svelte.d.ts
/// <reference types="svelte" />
export type ButtonProps = { label?: string };
// ...
```

`transform` runs after the [persistent parse cache](#persistent-parse-cache-cache)'s generated-text cache, so a changed transform is never served stale cached output - it always re-applies, even when the underlying `.d.ts` text was reused from a previous run. A transform that throws, or resolves to something other than a string, fails the whole `sveld` run with an error naming the file that failed.

There's no CLI flag for `transform`; set it via a config file or the programmatic `sveld()` API.

#### `typesOptions.indexTypes`

By default, `types/index.d.ts` only re-exports components:

```ts
export { default as Button } from "./Button.svelte";
```

A consumer who wants `ButtonProps` has to deep-import `my-lib/types/Button.svelte`. `typesOptions.indexTypes` re-exports the generated types from the barrel instead, so `import type { ButtonProps } from "my-lib"` works directly.

```js
sveld({
  types: true,
  typesOptions: {
    indexTypes: true,
  },
});
```

```ts
// types/index.d.ts
export { default as Button } from "./Button.svelte";

export type { ButtonProps } from "./Button.svelte";
```

```ts
import type { ButtonProps } from "my-lib";
```

`true` is shorthand for `{ props: true, exports: true }`: it re-exports each component's `Props` type, and (under [`format: "component"`](#dts-output-format-typesoptionsformat)) its `Exports` type. Pass an object to also re-export typedefs and/or contexts:

```js
typesOptions: {
  indexTypes: { props: true, typedefs: true, contexts: true },
}
```

`Props`/`Exports` names are unique per component by construction (they're derived from the module name), so they're always safe to re-export together. Typedef and context names are user-authored and can collide across components - when two components generate the same name, the first one in barrel order wins and every later collision is dropped with a one-line warning to `stderr`:

```
sveld: index.d.ts skips duplicate type export "TabsContext" from "./Tabs2.svelte" (already exported from "./Tabs.svelte").
```

`indexTypes` composes with [`exportTypes`](#typesoptionsexporttypes): a type that `exportTypes` keeps local to its component's `.d.ts` is never re-exported from the barrel either, since it wouldn't resolve.

Also available as `--types-index-types` on the CLI, mapped to the boolean form (`true` re-exports `Props`/`Exports` only) — the CLI can't express the per-kind object form. Pass `--types-index-types=false` to disable it explicitly.

#### `typesOptions.inline`

A TypeScript component that imports a type keeps that import in its `.d.ts`:

```svelte
<script lang="ts">
  import type { Size } from "./types";
  let { size }: { size: Size } = $props();
</script>
```

```ts
import type { Component } from "svelte";
import type { Size } from "./types";

type $Props = { size: Size };
export type MyComponentProps = $Props;
```

Publishers who don't ship their `.svelte` sources need `.d.ts` files without relative imports:
`./types.ts` might sit outside the published `types/` output directory, or the package might be
bundled to a single file. `typesOptions.inline: "local"` copies the imported declaration into
the `.d.ts` instead of importing it:

```js
sveld({
  types: true,
  typesOptions: {
    inline: "local",
  },
});
```

```ts
import type { Component } from "svelte";

type Size = "sm" | "md" | "lg";

type $Props = { size: Size };
export type MyComponentProps = $Props;
```

`"local"` follows:

- relative sources (`./types`) and tsconfig/jsconfig `paths` aliases;
- re-exports (`export { X as Y } from "./z"` and `export * from "./z"`);
- same-file dependencies (a copied type that itself references another type or interface
  declared in the same file copies that one too, before the type that references it).

It leaves alone:

- bare/package imports (`import type { CSSProperties } from "some-package"`) and `.svelte`
  sources — `"all"` covers bare imports, see below;
- `@extendProps`/`@extends` imports and `import("./x")` inline import types inside typedefs,
  which are unrelated mechanisms;
- `enum`, `class`, and `function` exports, which can't be safely copied as a `type`/`interface`.

An import that can't be safely inlined (a missing file, a missing export, one of the unsupported
export kinds above, or a name collision with something the component already declares — a
typedef, a context type, a local `type`/`interface`, or its `Props`/`Exports` type name) is left
as an import, with a [`types-inline-unresolved`](#diagnostic-codes) warning explaining why. If an
`import type { A, B } from "./x"` statement imports several names and even one of them can't be
inlined, the whole statement is kept and nothing from it is inlined — simpler, and always correct.

**`"all"`** additionally inlines bare/package imports:

```svelte
<script lang="ts">
  import type { HTMLButtonAttributes } from "svelte/elements";
  import type { Alignment } from "some-design-system";
  let { rest, align }: { rest: HTMLButtonAttributes; align: Alignment } = $props();
</script>
```

```js
sveld({
  types: true,
  typesOptions: {
    inline: "all",
  },
});
```

```ts
import type { Component } from "svelte";
import type { HTMLButtonAttributes } from "svelte/elements";

type Alignment = "start" | "center" | "end";

type $Props = { rest: HTMLButtonAttributes; align: Alignment };
export type MyComponentProps = $Props;
```

`some-design-system`'s `Alignment` got copied in, exactly like a `"local"` relative import would.
`svelte`/`svelte/elements` did not, even though `HTMLButtonAttributes` is itself a bare import a
real TypeScript checker could resolve and copy just as easily: those two specifiers are a
hard-coded allow-list and always stay imports under `"all"`, regardless of what they resolve to.
Copying framework types would freeze whatever Svelte version happened to be installed at
generation time into every consumer's `.d.ts` output, which defeats the point of importing them
from `svelte` in the first place.

Resolving a bare specifier to a file needs a real module resolver, so `"all"` uses the actual
TypeScript checker (the same one behind [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes)
and [`checkExamples`](#compile-checked-example-blocks-checkexamples), shared across all three when
more than one is enabled) rather than sveld's own AST-only pass. This makes `"all"` a **hard
requirement** on `typescript` 7+ and a resolvable `tsconfig.json` — same contract `resolveTypes`
already has (see [Requirements](#requirements)): if TypeScript can't be started, the run fails
loudly rather than silently falling back to `"local"` behavior. The requirement only actually
kicks in when there's at least one non-allow-listed bare import somewhere in the bundle to
resolve; an `"all"` run with nothing bare to inline never loads TypeScript at all.

A reference inside a copied bare declaration is chased exactly like a local one: a same-file
helper type is copied and recursed into, a relative/aliased import is followed the same way
`"local"` already does, and a further bare import goes back through the checker (again skipping
the svelte/svelte-elements allow-list). A reference that resolves to a TypeScript default-lib file
(e.g. `Element`, `EventTarget` from `lib.dom.d.ts`) is left alone — it's already global and needs
no import — the same way a local pass leaves an unimported name alone.

`@extendProps`/`@extends` inlining (replacing `import type { ButtonProps } from "./Button.svelte"`
with a copy of `Button`'s own generated declaration) is out of scope for both `"local"` and
`"all"`; that's a distinct, deferred mechanism, not covered here.

Copying from a large package can produce a large `.d.ts`: `svelte/elements`'s attribute-map
interfaces (`HTMLButtonAttributes` and friends) are individually sizable, and every type they
transitively reference gets copied too. Prefer `"local"` if you don't specifically need bare
imports inlined.

A component with at least one inlined declaration skips the generated-text cache (its output now
depends on another file's contents, not just its own source hash), though its *parse* is still
cached as usual. Also available as `--types-inline=<local|all>` on the CLI; `--types-inline=false`
resets to the default.

#### `markdownOptions.onAppend`

`markdownOptions.onAppend` fires on every heading, quote, paragraph, divider, and raw block written to the Markdown document, and receives the block's `type`, the in-progress `WriterMarkdown` document, and the full component map. Use it to inject extra content, e.g. a summary line under the `h1` title.

```js
import pkg from "./package.json" with { type: "json" };

sveld({
  markdown: true,
  markdownOptions: {
    onAppend: (type, document, components) => {
      if (type === "h1") {
        document.append(
          "quote",
          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
        );
      }
    },
  },
});
```

```md
# Component Index

> 1 components exported from sveld-scratch@1.0.0.
```

#### `markdownOptions.outDir`

With `markdown: true`, `sveld` writes a single `COMPONENT_INDEX.md` at the project root, documenting every component.

Use `markdownOptions.outDir` to split that into one `<ModuleName>.md` file per component, plus an index `README.md` that links to each one (and holds the Exports section when `documentExports` is on — per-component sections live entirely in their own file):

```js
sveld({
  markdown: true,
  markdownOptions: {
    // e.g. "docs/Button.md", "docs/README.md"
    outDir: "docs",
  },
});
```

`onAppend` still fires for both the index and every per-component file. `outFile` is ignored once `outDir` is set.

## Documenting Entry Exports

Most entry barrels re-export more than `.svelte` components. Set `documentExports: true` to add consts, functions, and types to the JSON and Markdown output.

```diff
sveld({
  json: true,
  markdown: true,
+  documentExports: true,
})
```

Example entry file:

```ts
// src/index.ts
export { default as Button } from "./Button.svelte";
export { VERSION } from "./constants";
export { clamp } from "./utils";
export type { Theme } from "./types";
```

From that barrel, `sveld` documents `VERSION`, `clamp`, and `Theme`. `Button` still goes through the component path. Type text is copied from source, not resolved with `tsc`, same as the rest of the tool.

Nested barrels are followed too: `export { X } from "./dir"`, where `./dir/index.js` itself re-exports `.svelte` files, resolves `X` to the underlying component without needing `--glob`.

JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each item has `name`, `kind`, type text, optional JSDoc `description`, `source`, and — same as props — optional `@deprecated` and pass-through `tags`. A deprecated export's name is struck through in the Markdown table, same as a deprecated prop. See [`@deprecated`](#deprecated).

An overloaded function (repeated `export function f(...)` signatures, or an import re-exported through a barrel) always documents the implementation signature, i.e. the last declaration. An `enum` export's `type` is the literal union of its members' values (`"A" | "B"` for a string enum, `0 | 1` for a numeric one), falling back to the bare enum name when a member's value can't be determined (e.g. a computed initializer). When two different modules export the same name (most commonly via `export * from "./a"; export * from "./b"`), `sveld` keeps whichever was declared first and prints a warning; it does not silently pick one or emit both.

## JSON Output

When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
component API. For stable output, generated `events` arrays are emitted in deterministic sorted order.

The JSON Schema lives on GitHub ([path to file](https://github.com/carbon-design-system/sveld/blob/main/schema/component-api.schema.json), [raw URL](https://raw.githubusercontent.com/carbon-design-system/sveld/main/schema/component-api.schema.json)). Use it to validate generated `COMPONENT_API.json` files. Optional fields may be missing when the parser has no stable source for that metadata.

`sveld` also ships the schema as a package subpath, so you don't need network access to validate at build time:

```ts
import schema from "sveld/schema/component-api.schema.json" with { type: "json" };
```

`require.resolve("sveld/schema/component-api.schema.json")` works too. The `$id` in the schema still points at the `main` branch on GitHub for tooling that dereferences it by URL, but that URL always reflects the latest release; the copy packaged with your installed `sveld` version is the authoritative one for the output it produced.

```ts
interface ComponentApiJson {
  schemaVersion: 1;
  generator: {
    name: string;
    version: string;
    svelteVersion: string;
  };
  total: number;
  components: ComponentDocApi[];
  // Present only when `documentExports` is enabled.
  totalExports?: number;
  exports?: EntryExport[];
}

interface EntryExport {
  name: string;
  kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
  type?: string;
  value?: string;
  description?: string;
  deprecated?: string | true;
  tags?: Array<{ name: string; body: string }>;
  source?: string;
  isTypeOnly: boolean;
}

interface SourceRange {
  start: SourcePosition;
  end: SourcePosition;
}

interface SourcePosition {
  line: number;
  column: number;
}

interface ComponentDocApi {
  moduleName: string;
  filePath: string;
  source?: SourceRange;
  syntaxMode: "legacy" | "runes";
  scriptLanguage?: "js" | "ts";
  props: ComponentProp[];
  moduleExports: ComponentProp[];
  slots: ComponentSlot[];
  events: ComponentEvent[];
  typedefs: TypeDef[];
  generics: null | [name: string, type: string];
  rest_props?: RestProps;
  extends?: { interface: string; import: string };
  componentComment?: string;
  componentCommentSource?: SourceRange;
  contexts?: ComponentContext[];
  customElementTag?: string;
}

interface ComponentProp {
  name: string;
  localName?: string;
  kind: "let" | "const" | "function";
  constant: boolean;
  type?: string;
  typeSource?: "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
  value?: string;
  defaultValue?: {
    raw: string;
    kind: "literal" | "array" | "object" | "expression" | "function" | "unknown";
    value?: unknown;
  };
  description?: string;
  params?: Array<{ name: string; type: string; description?: string; optional?: boolean }>;
  returnType?: string;
  isFunction: boolean;
  isFunctionDeclaration: boolean;
  isRequired: boolean;
  reactive: boolean;
  binding?: "readonly" | "writable";
  bindable?: true;
  source?: SourceRange;
}

interface ComponentSlot {
  name?: string | null;
  default: boolean;
  fallback?: string;
  slot_props?: string;
  description?: string;
  tags?: Array<{ name: string; body: string }>;
  source?: SourceRange;
}

type ComponentEvent =
  | {
      type: "forwarded";
      name: string;
      element: string;
      description?: string;
      detail?: string;
      source?: SourceRange;
    }
  | {
      type: "dispatched";
      name: string;
      detail?: string;
      description?: string;
      source?: SourceRange;
    };
```

`source` fields appear only when the Svelte or JavaScript AST has stable positions. They omit source text and raw character offsets.

`SourcePosition.line` is 1-based. `SourcePosition.column` is 0-based.

Prop metadata is additive and keeps the older public fields:

- `name` is always the public prop name. For runes `$props()` aliases such as `let { class: className } = $props()`, `localName` is emitted only when the local binding differs.
- `typeSource` identifies the conservative source of the emitted `type`: TypeScript annotation, JSDoc, initializer/default inference, other parser inference, or unknown fallback.
- `value` remains the raw default expression string. `defaultValue` adds structured metadata with the same raw expression, a coarse `kind`, and a parsed `value` only for JSON-safe literals, arrays, and plain objects. `sveld` does not evaluate arbitrary code.
- `bindable: true` is emitted only for props explicitly declared with Svelte 5 `$bindable(...)`. Missing `bindable` should be treated as false.

## Custom Elements Manifest

Set `customElements: true` to emit a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) (`custom-elements.json`, `schemaVersion: "1.0.0"`). This is the interchange format the web-components ecosystem standardized on: Storybook autodocs, VS Code/JetBrains HTML data, and other CEM-aware tooling can all read it directly.

```diff
sveld({
+  customElements: true,
})
```

- **`customElements`** (boolean, optional): Generate `custom-elements.json`.
- **`customElementsOptions.outFile`** (string, optional, default: `"custom-elements.json"`): Override the output path.
- Also available as the `--custom-elements` CLI flag.

Each exported component becomes one `javascript-module` with a class declaration:

- **Members** — every `export let`/`const` prop becomes a `ClassField` (`name`, `type.text`, `default`, `description`, `deprecated`; `readonly: true` for an `export const`). An accessor prop (`export function`) becomes a `ClassMethod` (`name`, `static: false`, `parameters`, `return.type.text`) instead — see [Accessor methods](#accessor-methods) below.
- **Attributes** — every prop becomes an attribute (Svelte's custom-element runtime observes one for every prop by default), excluding `export function` accessors. The attribute name is `prop.toLowerCase()` by default, or the `customElement.props.<name>.attribute` config when set — see [Object-form `customElement` config](#object-form-customelement-config) below. Props that collide on the same attribute name keep the first (in declaration order); the rest are skipped with a console warning, since which one wins at runtime is ambiguous.
- **Events** — dispatched events (`createEventDispatcher()`, and `$host().dispatchEvent(...)` from inside a custom element) become `{ name, type: { text: "CustomEvent<...>" } }`. Forwarded (`on:click`) events are left out, since they aren't dispatched by the component's own class.
- **Slots** — named and default slots, with descriptions. The default slot's `name` is `""`, matching the CEM convention.
- **`cssParts`/`cssProperties`** — from `@csspart`/`@cssprop` JSDoc tags — see [CSS parts and custom properties](#css-parts-and-custom-properties) below.

When a component sets `<svelte:options customElement="x-foo" />` (or the object form, `<svelte:options customElement={{ tag: "x-foo" }} />`), its declaration gets `tagName: "x-foo"` and `customElement: true`, and the module's `exports` include a `custom-element-definition` export alongside the plain `js` export.

Components without `customElement` still emit a plain class declaration (no `tagName`/`customElement`) — useful for documenting the class shape even before it's compiled as a custom element, but the manifest is most useful for `customElement`-compiled builds, where downstream tooling can resolve `tagName`, `attributes`, and `events` for actual custom-element usage.

### Object-form `customElement` config

The object form of `<svelte:options customElement={{ ... }} />` is read in full, not just `tag`:

```svelte
<svelte:options
  customElement={{
    tag: "x-widget",
    shadow: "none",
    props: {
      variant: { attribute: "data-variant" },
      active: { reflect: true },
      tags: { type: "Array" }
    },
    extend: (customElementConstructor) => customElementConstructor
  }}
/>
```

| Config | Effect on the manifest |
| --- | --- |
| `props.<name>.attribute` | Overrides that prop's attribute name (default: `name.toLowerCase()`). `attribute: false` omits the prop's attribute entirely. |
| `props.<name>.reflect` | Adds `reflects: true` to that prop's attribute. |
| `props.<name>.type` | `"Array"`/`"Object"` appends a note to the attribute's description that the value is JSON-serialized (matching Svelte's runtime `JSON.stringify`/`JSON.parse` for those types); the attribute's `type.text` is still the prop's own TS type, not this config value. |
| `shadow`, `extend` | Parsed and available on the raw `ParsedComponent.customElement` (Node API), but don't affect the manifest. |

This full config (`tag`, `shadow`, `props`, `extend`) is also on `ParsedComponent.customElement` in the JSON output (`COMPONENT_API.json`), alongside the existing `customElementTag` shorthand.

### Accessor methods

An `export function` prop (a Svelte accessor, e.g. `export function focus() { ... }`) becomes a `ClassMethod`, not a `ClassField`, and is excluded from `attributes` (accessors aren't part of Svelte's props definition). `parameters`/`return` come from `@param`/`@returns` JSDoc when present, otherwise from splitting the function's TypeScript signature text (e.g. `(id: string) => boolean`).

### CSS parts and custom properties

Document shadow-DOM styling hooks with `@csspart`/`@cssprop` (alias `@cssproperty`) tags in the component's own JSDoc comment (the same comment block `@slot` tags go in):

```js
/**
 * @csspart header - Styles the header region.
 * @cssprop {Color} [--card-background=white] - Background color of the card.
 * @cssprop --card-border-color - Border color of the card.
 */
```

`@cssprop`'s `{type}` and `[--name=default]` are both optional, following the [Custom Elements Manifest analyzer](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#css-custom-properties) grammar. These populate `cssParts`/`cssProperties` on the class declaration, and `ParsedComponent.cssParts`/`cssProperties` in the JSON output; the Markdown writer renders them as two extra tables when present.

### Consuming the manifest

Most tools discover `custom-elements.json` through a `customElements` field in `package.json`, pointing at the generated file:

```json
{
  "customElements": "custom-elements.json"
}
```

With that in place:

- The [VS Code custom elements extension](https://marketplace.visualstudio.com/items?itemName=BendingSpoons.vscode-custom-elements) and JetBrains IDEs pick it up automatically, giving tag name, attribute, and slot completion/hover in HTML and Svelte templates.
- [Storybook](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#extracting-argtypes) for web components reads the manifest to auto-generate `argTypes` (controls, docs tables) for `customElement`-compiled components, once you point it at the file (e.g. `setCustomElementsManifest` from `@storybook/web-components`, or `customElements: "custom-elements.json"` in `.storybook/main.js`).
- Any other tool built against the [Custom Elements Manifest spec](https://github.com/webcomponents/custom-elements-manifest) (API viewers, doc generators, linters) can read the file directly without sveld-specific integration.

## llms.txt Output

Set `llms: true` to emit an [`llms.txt`](https://llmstxt.org) / `llms-full.txt` pair: `llms.txt` is an index of every exported component (one link plus a one-line summary each), and `llms-full.txt` is the flattened full reference (every component's Props, Bindings, Events, Slots/Snippets, Typedefs, and Module exports, as terse Markdown tables). Props and Events Description columns include `@since`/`@example` tags, same as `COMPONENT_INDEX.md`.

```diff
sveld({
+  llms: true,
})
```

- **`llms`** (boolean, optional): Generate `llms.txt` and `llms-full.txt`. Also available as the `--llms` CLI flag.
- **`llmsOptions`** (object, optional):
  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`, e.g. `[Button](<linkBase>/Button)`. Set this to your published docs site's base path.
  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title. Omitted when neither is set.

Each component's one-line summary in `llms.txt` is the first sentence of its [`@component` comment](#component-comments), falling back to `"Component"`. Set `documentExports: true` to also list entry-barrel exports (consts, functions, types) in `llms.txt` under an `## Exports` heading.

## Custom Writers

`json`, `markdown`, `types`, and `custom-elements` are all built on the same
extensibility point: a small writer registry that third parties can use to
add new output formats without a core PR. This is a stable, public part of
sveld's API — the four built-in writers register through it in
`src/writer/built-in-writers.ts`, there is no separate "internal" path.

### The `OutputWriter` contract

```ts
interface OutputWriter<TOptions = unknown> {
  name: string;
  /** Which component set this writer expects. @default "exported" */
  componentSet?: "exported" | "all";
  write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
}
```

- **`name`** is how the plugin's `additionalWriters` option (and anything else
  that calls `getWriter`) looks the writer up. Pick something that won't
  collide with `types` / `json` / `markdown` / `custom-elements` or another
  third-party writer.
- **`componentSet`** picks which map `write` receives:
  - `"exported"` (the default) — components reachable from the entry barrel,
    keyed by `moduleName`. This is what `json` / `markdown` /
    `custom-elements` use.
  - `"all"` — every `--glob`-discovered `.svelte` file, keyed by resolved
    `filePath` instead of `moduleName` (two files in different directories
    can share a basename). This is what `types` uses.
- **`write`** receives a `ComponentDocs` (`Map<string, ComponentDocApi>`) —
  the same `ComponentDocApi` shape documented in [JSON Output](#json-output).
  Don't iterate the raw map yourself; call `buildComponentApiDocument(components, { entryExports })`
  (also exported from `sveld`) to get the sorted, `diagnostics`-stripped,
  schema-versioned document the built-in writers build from. It's memoized
  per `components` map, so calling it more than once in one run is free.
- **`options`** always carries `dryRun` alongside whatever fields the writer
  itself defines. See [The `dryRun` contract](#the-dryrun-contract) below.

### Registering a writer

```ts
import { registerWriter } from "sveld";

registerWriter({
  name: "my-format",
  write(components, options) {
    // ...
  },
});
```

`registerWriter` is a side effect — call it once, before the plugin or CLI
runs, e.g. at the top of `vite.config.ts` or `sveld.config.ts`, or in a file
either of those imports.

Registering a `name` that's already taken — a built-in writer's name, or
another `registerWriter` call — throws instead of silently overwriting it.
Pass `{ replace: true }` as a second argument when overwriting is intentional
(e.g. re-registering a writer module during development):

```ts
registerWriter(
  {
    name: "my-format",
    write(components, options) {
      // ...
    },
  },
  { replace: true },
);
```

### The `dryRun` contract

Every writer — built-in or `additionalWriters` — receives `dryRun: true` in
its `options` when the run is `sveld --dry-run` (or `{ dryRun: true }` from
the programmatic API). A writer must check it and skip touching disk; sveld
does not do this for you:

```ts
import { writeFileSync } from "node:fs";

registerWriter({
  name: "my-format",
  write(components, options: { outFile: string; dryRun?: boolean }) {
    if (options.dryRun) {
      console.log(`would write "${options.outFile}"`);
      return;
    }
    writeFileSync(options.outFile, "...");
  },
});
```

A writer that throws — synchronously or from a rejected promise — has its
error re-thrown as `sveld: writer "<name>" failed: <message>`, with the
original error attached as `cause`, so a broken third-party writer never
fails silently or without saying which one.

### Running it via the plugin

```ts
// vite.config.ts
import sveld from "sveld";
import "./writers/my-format"; // calls registerWriter as a side effect

export default {
  plugins: [
    sveld({
      additionalWriters: {
        "my-format": { outFile: "MY_FORMAT.txt" },
      },
    }),
  ],
};
```

`additionalWriters` is keyed by the writer's registered `name`; the value is
whatever options object that writer's `write` expects. An unknown name logs a
warning and is skipped rather than failing the build. Registered writers run
alongside whichever built-in outputs (`types` / `json` / `markdown` /
`customElements`) are also enabled, and the same option is available from the
programmatic Node API and from `sveld.config.ts` (`additionalWriters` lives on
the options shared by all three entry points).

### Worked example: a `components.txt` name-list writer

Looking for an `llms.txt` writer specifically? Sveld ships one — see [llms.txt Output](#llmstxt-output). This example is a much smaller custom writer, just to show the pattern: a plain-text list of exported component names, needing nothing beyond `ComponentApiDocument`.

```ts
// writers/components-txt-writer.ts
import { writeFileSync } from "node:fs";
import { join } from "node:path";
import { buildComponentApiDocument, registerWriter } from "sveld";

interface ComponentsTxtWriterOptions {
  outFile?: string;
}

registerWriter<ComponentsTxtWriterOptions>({
  name: "components-txt",
  componentSet: "exported",
  write(components, options = {}) {
    const document = buildComponentApiDocument(components);
    const rendered = document.components.map((component) => component.moduleName).join("\n");

    writeFileSync(join(process.cwd(), options.outFile ?? "components.txt"), rendered);
  },
});
```

```ts
// vite.config.ts
import sveld from "sveld";
import "./writers/components-txt-writer";

export default {
  plugins: [
    sveld({
      additionalWriters: {
        "components-txt": { outFile: "components.txt" },
      },
    }),
  ],
};
```

Running a build now produces a `components.txt` alongside the usual output,
listing one exported component name per line.

## API Reference

### `reactive`

The `reactive` field in generated JSON is a heuristic. It does not fully answer whether a parent can use `bind:prop` in Svelte.

`sveld` marks `reactive: true` when it finds internal evidence that a prop is writable, including:

- the prop is assigned or mutated inside the component
- the prop is marked bindable in runes mode with `$bindable(...)`
- the prop is used as the target of `bind:*` on an element or child component
- wrapper-forwarded bindings such as `bind:value`, `bind:selected`, and `bind:ref`

Local variables or parameters that shadow a prop name do not count as writes to the exported prop.

`reactive: false` means `sveld` found no such evidence. It does not imply that parent-side `bind:` usage is impossible.

### `binding`

The optional `binding` field documents a prop's intended `bind:` contract. It is separate from `reactive` and is never inferred from internal writes or `$bindable()`.

Use `@bindable readonly` for component-owned or output-style bindings where the consumer binds to the current value emitted by the component:

```svelte
<script>
  /**
   * Bind to the current value emitted by the component.
   * @bindable readonly
   */
  export let size = undefined;
</script>
```

Use `@bindable writable` for two-way or shared state bindings where either the consumer or component may control the value:

```svelte
<script>
  /**
   * Bind to state controlled by either the consumer or component.
   * @bindable writable
   */
  export let open = false;
</script>
```

Generated JSON includes `"binding": "readonly"` or `"binding": "writable"` for annotated props. Unannotated props omit the field.

This is documentation only. Generated `.svelte.d.ts` prop types do not change. TypeScript cannot express Svelte binding direction reliably.

### `@type`

Without a `@type` annotation, `sveld` infers the primitive type for a prop:

```js
export let kind = "primary";
// inferred type: "string"
```

For template literal default values, `sveld` infers the type as `string`:

```js
export let id = `ccs-${Math.random().toString(36)}`;
// inferred type: "string"
```

Use the `@type` tag to document the type explicitly. In the example below, `kind` is a string union.

For `lang="ts"` components, prefer native TypeScript annotations when you already have them. `@type` still helps in JavaScript components, for overriding inferred types, and when the AST cannot recover a sharper type.

**Signature:**

```js
/**
 * Optional description
 * @type {Type}
 */
```

**Example:**

```svelte
<script>
  let {
    /**
     * Specify the kind of button
     * @type {"primary" | "secondary" | "tertiary"}
     */
    kind = "primary",
    /**
     * Specify the Carbon icon to render
     * @type {typeof import("carbon-icons-svelte").CarbonIcon}
     */
    renderIcon = Close20,
  } = $props();
</script>
```

For runes components with multiple destructured props, put JSDoc on the property you want to document. A declaration-level block is a fallback when the destructure exposes a single public prop.

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Specify the kind of button
   * @type {"primary" | "secondary" | "tertiary"}
   */
  export let kind = "primary";

  /**
   * Specify the Carbon icon to render
   * @type {typeof import("carbon-icons-svelte").CarbonIcon}
   */
  export let renderIcon = Close20;
</script>
```

</details>

#### Importing types

`sveld` supports TypeScript's [`import(...)` type syntax](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#import-types), so a `@type` or `@typedef` can reference a type from another module without a top-level `import`. The expression is copied verbatim into the generated `.d.ts` and resolves the same way as hand-written TypeScript:

- `import("module").Type` references an exported **type**.
- `typeof import("module").value` references the type of an exported **value**.
- `import("svelte").ComponentProps<...>` and other utility types compose with imports.

This keeps third-party types (Svelte stores, another component's props, library types) out of runtime imports while still showing up in IntelliSense for consumers.

**Example:**

```svelte
<script>
  /**
   * A store from `svelte/store`. No top-level `import` required.
   * @type {import("svelte/store").Writable<string>}
   */
  export let value;

  /**
   * `typeof import(...)` references the type of a value export, here the
   * `writable` factory itself rather than a type it exports.
   * @type {typeof import("svelte/store").writable}
   */
  export let createStore;

  /**
   * Reuse another component's props with Svelte's `ComponentProps` utility.
   * @type {import("svelte").ComponentProps<import("svelte").SvelteComponent>}
   */
  export let buttonProps;

  /**
   * `import(...)` works inside a `@typedef` too, which helps when typing values shared via `setContext` / `getContext`.
   *
   * @typedef {{ rows: import("svelte/store").Writable<string[]>; selected: import("svelte/store").Readable<number> }} TableContext
   */

  /** @type {TableContext} */
  export let context;
</script>
```

Output:

```ts
export interface TableContext {
  rows: import("svelte/store").Writable<string[]>;
  selected: import("svelte/store").Readable<number>;
}

export type ComponentProps = {
  /** @default undefined */
  value: import("svelte/store").Writable<string>;
  /** @default undefined */
  createStore: typeof import("svelte/store").writable;
  /** @default undefined */
  buttonProps: import("svelte").ComponentProps<import("svelte").SvelteComponent>;
  /** @default undefined */
  context: TableContext;
};
```

#### Prefer `unknown` over `any`

When a prop accepts data whose shape you do not know ahead of time, annotate it as `unknown` rather than `any`. `sveld` preserves either keyword in the emitted prop type, but they behave differently for consumers: `unknown` forces a narrowing check before use; `any` disables type checking everywhere the value flows. Reserve `any` for real escape hatches.

**Example:**

```svelte
<script>
  /**
   * A value of unknown shape. Prefer `unknown` over `any`: consumers must
   * narrow it before use instead of silently opting out of type checking.
   *
   * @type {unknown}
   */
  export let payload;

  /**
   * An escape hatch typed as `any`, shown for contrast. `any` disables type
   * checking everywhere it flows, so reach for `unknown` at boundaries instead.
   *
   * @type {any}
   */
  export let raw;
</script>
```

Output:

```ts
export type ComponentProps = {
  /** @default undefined */
  payload: unknown;
  /** @default undefined */
  raw: any;
};
```

Consumers must narrow an `unknown` prop before using it, while an `any` prop silently accepts anything:

```ts
function handle(props: ComponentProps) {
  // Error: 'payload' is of type 'unknown'. Narrow it first.
  props.payload.toUpperCase();

  if (typeof props.payload === "string") {
    props.payload.toUpperCase(); // OK after narrowing
  }
}
```

### `@default`

By default, `sveld` infers the `@default` value from the prop's initializer and includes it in the generated TypeScript definitions:

```svelte
<script>
  export let open = false;
</script>
```

```ts
/**
 * @default false
 */
open?: boolean;
```

Use `@default` to document the default value. When you supply `@default`, `sveld` uses it instead of the inferred value and avoids duplicate `@default` tags in the output.

Use `@default` when the initializer references a variable or expression that means nothing to consumers:

```svelte
<script>
  const defaultFilter = () => true;

  /**
   * @default () => true
   * @type {(item: string, value: string) => boolean}
   */
  export let shouldFilter = defaultFilter;
</script>
```

```ts
/**
 * @default () => true
 */
shouldFilter?: (item: string, value: string) => boolean;
```

#### Identifier resolution

When a prop's initializer is a variable reference, `sveld` resolves it to the actual value:

```svelte
<script>
  const DEFAULT_SIZE = "md";

  /** @type {"sm" | "md" | "lg"} */
  export let size = DEFAULT_SIZE;
</script>
```

```ts
/**
 * @default "md"
 */
size?: "sm" | "md" | "lg";
```

Chained references are also resolved:

```svelte
<script>
  const ACTUAL_VALUE = 42;
  const ALIAS = ACTUAL_VALUE;

  export let count = ALIAS;
</script>
```

```ts
/**
 * @default 42
 */
count?: number;
```

Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value. If the identifier cannot be resolved (e.g., it is imported from another module), the variable name is used as-is.

When an explicit `@default` annotation is provided, it always takes precedence over the resolved value.

### `@typedef`

The `@typedef` tag defines a shared type used multiple times in a component. All typedefs in a component are exported from the generated `.d.ts`.

**Signature:**

```js
/**
 * @typedef {Type} TypeName
 */
```

**Example:**

```svelte
<script>
  /**
   * @typedef {string} AuthorName
   * @typedef {{ name?: AuthorName; dob?: string; }} Author
   */

  let {
    /** @type {Author} */
    author = {},
    /** @type {Author[]} */
    authors = [],
  } = $props();
</script>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * @typedef {string} AuthorName
   * @typedef {{ name?: AuthorName; dob?: string; }} Author
   */

  /** @type {Author} */
  export let author = {};

  /** @type {Author[]} */
  export let authors = [];
</script>
```

</details>

#### Using `@property` for complex typedefs

For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE. See the [`@property`](#property) reference for the tag's valid contexts.

**Signature:**

```js
/**
 * Type description
 * @typedef {object} TypeName
 * @property {Type} propertyName - Property description
 */
```

**Example:**

```svelte
<script>
  /**
   * Represents a user in the system
   * @typedef {object} User
   * @property {string} name - The user's full name
   * @property {string} email - The user's email address
   * @property {number} age - The user's age in years
   */

  /** @type {User} */
  let { user = { name: "John", email: "john@example.com", age: 30 } } = $props();
</script>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Represents a user in the system
   * @typedef {object} User
   * @property {string} name - The user's full name
   * @property {string} email - The user's email address
   * @property {number} age - The user's age in years
   */

  /** @type {User} */
  export let user = { name: "John", email: "john@example.com", age: 30 };
</script>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export type User = {
  /** The user's full name */
  name: string;
  /** The user's email address */
  email: string;
  /** The user's age in years */
  age: number;
};

export type ComponentProps = {
  /**
   * Represents a user in the system
   * @default { name: "John", email: "john@example.com", age: 30 }
   */
  user?: User;
};
```

#### Optional properties and default values

Use square brackets for optional properties, per JSDoc. Default values use `[propertyName=defaultValue]`.

**Signature:**

```js
/**
 * @typedef {object} TypeName
 * @property {Type} [optionalProperty] - Optional property description
 * @property {Type} [propertyWithDefault=defaultValue] - Property with default value
 */
```

**Example:**

```svelte
<script>
  /**
   * Configuration options for the component
   * @typedef {object} ComponentConfig
   * @property {boolean} enabled - Whether the component is enabled
   * @property {string} theme - The component theme
   * @property {number} [timeout=5000] - Optional timeout in milliseconds
   * @property {boolean} [debug] - Optional debug mode flag
   */

  /** @type {ComponentConfig} */
  let { config = { enabled: true, theme: "dark" } } = $props();
</script>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Configuration options for the component
   * @typedef {object} ComponentConfig
   * @property {boolean} enabled - Whether the component is enabled
   * @property {string} theme - The component theme
   * @property {number} [timeout=5000] - Optional timeout in milliseconds
   * @property {boolean} [debug] - Optional debug mode flag
   */

  /** @type {ComponentConfig} */
  export let config = { enabled: true, theme: "dark" };
</script>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export type ComponentConfig = {
  /** Whether the component is enabled */
  enabled: boolean;
  /** The component theme */
  theme: string;
  /** Optional timeout in milliseconds @default 5000 */
  timeout?: number;
  /** Optional debug mode flag */
  debug?: boolean;
};

export type ComponentProps = {
  /**
   * Configuration options for the component
   * @default { enabled: true, theme: "dark" }
   */
  config?: ComponentConfig;
};
```

> The inline syntax `@typedef {{ name: string }} User` still works for backwards compatibility.

#### Discriminated unions

A `@typedef` can be a union of object literals, optionally mixed with primitive members. `sveld` emits these as `export type X = ...` aliases (not `interface`), so the discriminant narrows correctly on the consumer side.

**Signature:**

```js
/**
 * @typedef {A | B | C} TypeName
 */
```

**Example:**

```svelte
<script>
  /**
   * @typedef {{ kind: "success"; value: string } | { kind: "error"; error: Error }} Result
   * @typedef {{ ok: true; data: number } | { ok: false; reason: string } | "pending"} Status
   */

  /** @type {Result} */
  export let result = { kind: "success", value: "ok" };

  /** @type {Status} */
  export let status = "pending";
</script>
```

Output:

```ts
export type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };

export type Status = { ok: true; data: number } | { ok: false; reason: string } | "pending";

export type ComponentProps = {
  /** @default { kind: "success", value: "ok" } */
  result?: Result;
  /** @default "pending" */
  status?: Status;
};
```

Consumers can then narrow on the discriminant:

```ts
function describe(r: Result) {
  switch (r.kind) {
    case "success":
      return r.value;
    case "error":
      return r.error.message;
  }
}
```

The same pattern works inline via `@type`, which is useful when the union is only used for a single prop:

```js
/** @type {{ kind: "success"; value: string } | { kind: "error"; error: Error }} */
export let result = { kind: "success", value: "ok" };
```

In `<script lang="ts">` components, write the type alias directly. `sveld` preserves it in the emitted `.d.ts`:

```svelte
<script lang="ts">
  type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };

  let { result = { kind: "success", value: "ok" } }: { result?: Result } = $props();
</script>
```

#### Branded types

A branded type is a primitive plus a unique marker so values like `UserId` are not interchangeable with any other `string`. At runtime it is still the underlying primitive; TypeScript treats the brand as a separate type. Declare the brand inline with `@type`. `sveld` copies the intersection verbatim into the emitted prop type, so the brand shows up in IntelliSense, autocomplete, and hover tooltips on the consumer side.

**Example:**

```svelte
<script>
  /**
   * A branded string. At runtime it is a plain `string`, but the brand makes it
   * a distinct domain type that other strings cannot be assigned to.
   *
   * @type {string & { readonly __brand: "UserId" }}
   */
  export let userId;

  /**
   * A branded number representing a monetary amount in cents.
   *
   * @type {number & { readonly __brand: "Cents" }}
   */
  export let amount;
</script>
```

Output:

```ts
export type ComponentProps = {
  /**
   * A branded string. At runtime it is a plain `string`, but the brand makes it
   * a distinct domain type that other strings cannot be assigned to.
   * @default undefined
   */
  userId: string & { readonly __brand: "UserId" };

  /**
   * A branded number representing a monetary amount in cents.
   * @default undefined
   */
  amount: number & { readonly __brand: "Cents" };
};
```

Consumers construct branded values with a narrowing cast, then get compile-time protection against mixing them up:

```ts
const userId = "user_123" as ComponentProps["userId"];

// Error: a plain string is not assignable to the branded userId
component.$set({ userId: "user_123" });
```

#### Utility types

`sveld` preserves TypeScript utility types verbatim, so a prop type can be derived from an existing `@typedef` instead of restating its fields. `Pick`, `Omit`, `Partial`, `Required`, `Readonly`, `ReturnType`, `Parameters`, and `Awaited` pass through unchanged. When the base type changes, derived props follow.

**Example:**

```svelte
<script>
  /**
   * @typedef {{ id: string; size: "sm" | "md" | "lg"; disabled: boolean }} Options
   */

  /**
   * @typedef {() => Options} Factory
   */

  /**
   * A subset of `Options`.
   * @type {Pick<Options, "id" | "size">}
   */
  export let summary;

  /**
   * Everything in `Options` except `disabled`.
   * @type {Omit<Options, "disabled">}
   */
  export let editable;

  /**
   * Derived from the factory's return type rather than restated.
   * @type {ReturnType<Factory>}
   */
  export let defaults;

  /**
   * The resolved value of an async source.
   * @type {Awaited<Promise<Options>>}
   */
  export let resolved;
</script>
```

Output:

```ts
export interface Options {
  id: string;
  size: "sm" | "md" | "lg";
  disabled: boolean;
}

export type Factory = () => Options;

export type ComponentProps = {
  summary: Pick<Options, "id" | "size">;
  editable: Omit<Options, "disabled">;
  defaults: ReturnType<Factory>;
  resolved: Awaited<Promise<Options>>;
};
```

#### Type guards

A prop typed as a [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) (`value is T`) lets a component accept a user-defined type guard. `sveld` copies the predicate verbatim, whether you write it inline with `@type` or name it with `@typedef`, so narrowing survives in the generated `.d.ts`. Name guards `isX` or `hasX`, and make sure the implementation actually checks what the predicate claims.

**Example:**

```svelte
<script>
  /**
   * @typedef {{ id: string; name: string }} User
   */

  /**
   * A type guard. It accepts an `unknown` value and returns a type predicate,
   * so callers can narrow `unknown` to `User` before accessing its fields.
   *
   * @type {(value: unknown) => value is User}
   */
  export let isUser;

  /**
   * A type guard expressed as a reusable `@typedef`.
   *
   * @typedef {(value: unknown) => value is User} UserGuard
   */

  /** @type {UserGuard} */
  export let validate;
</script>
```

Output:

```ts
export interface User {
  id: string;
  name: string;
}

export type UserGuard = (value: unknown) => value is User;

export type ComponentProps = {
  isUser: (value: unknown) => value is User;
  validate: UserGuard;
};
```

Consumers use the guard to narrow an `unknown` value:

```ts
function render(value: unknown, props: ComponentProps) {
  if (props.isUser(value)) {
    value.name; // narrowed to User
  }
}
```

### `@property`

`@property` documents one field of an object. `sveld` only reads it in two places: directly inside a `@typedef {object}` block, and directly inside an `@event` block (after an explicit `@type {object}`, or with no `@type` at all — `sveld` builds the detail type from the collected `@property` entries). It has no effect anywhere else.

**Valid contexts:**

| Context | Behavior |
| :- | :- |
| After `@typedef {object} Name`, in the same comment block | Builds `Name`'s fields. See [Using `@property` for complex typedefs](#using-property-for-complex-typedefs). |
| After `@event eventname`, in the same comment block | Builds the event's detail type. See [Using `@property` for complex event details](#using-property-for-complex-event-details). |
| A plain prop with no `@typedef`/`@type {object}` | Not structured. Folded into the prop's description as literal text (`@property name - description`). |
| Before a `@slot` / `@snippet` line | Dropped entirely — no structured output, and unlike other unrecognized tags in that position, it is not folded into the slot's description either. |
| Inside `@callback` | Not read. Use `@param` for callback parameters instead. |

**Signature:**

```js
/**
 * @typedef {object} TypeName
 * @property {Type} propertyName - Property description
 *
 * @event eventname
 * @type {object}
 * @property {Type} propertyName - Property description
 */
```

Both forms support the same modifiers as typedef properties elsewhere in this doc: optional properties (`[name]`), default values (`[name=value]`), and nested/discriminated-union shapes. See the linked sections above for full signatures and worked examples with generated output.

### `@callback`

The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.

Use it for callback props when you do not want inline function type syntax.

**Signature:**

```js
/**
 * Optional description
 * @callback CallbackName
 * @param {Type} paramName - Parameter description
 * @returns {ReturnType}
 */
```

**Example:**

```svelte
<script>
  /**
   * Callback fired when the value changes
   * @callback OnChange
   * @param {string} value - The new value
   * @param {number} index - The index of the changed item
   * @returns {void}
   */

  /** @type {OnChange} */
  let { onChange = (value, index) => {} } = $props();
</script>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Callback fired when the value changes
   * @callback OnChange
   * @param {string} value - The new value
   * @param {number} index - The index of the changed item
   * @returns {void}
   */

  /** @type {OnChange} */
  export let onChange = (value, index) => {};
</script>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
/**
 * Callback fired when the value changes
 */
export type OnChange = (value: string, index: number) => void;

export type ComponentProps = {
  /**
   * Callback fired when the value changes
   */
  onChange?: OnChange;
};
```

Callbacks can be combined with `@typedef` in the same comment block:

```js
/**
 * @typedef {"asc" | "desc"} SortDirection
 * @callback SortFn
 * @param {any} a
 * @param {any} b
 * @param {SortDirection} direction
 * @returns {number}
 */
```

When `@returns` is omitted, the return type defaults to `void`. When no `@param` tags are present, the callback is typed as a no-argument function.

### `@slot` / `@snippet`

Use `@slot` to type component slots. In Svelte 5 runes components, `@snippet` is an alias. Both are non-standard JSDoc tags.

Descriptions are optional for every slot, including the default slot. Put prose in the same `/** */` block above `@slot` / `@snippet`, or an inline description on the `@slot` line for named slots.

**Signature:**

```js
/**
 * @slot {Type} slot-name [slot description]
 * @snippet {Type} snippet-name [snippet description]
 */
```

Omit the `slot-name` to type the default slot. `{Type}` itself is required; omitting it falls back to `Record<string, never>` and raises a [`sveld/slot-missing-type`](#diagnostic-codes) warning.

```js
/**
 * @slot {Type}
 * @snippet {Type}
 */
```

**Example:**

```svelte
<script>
  /**
   * @snippet {{ prop: number; doubled: number; }}
   * @snippet {{}} title
   * @snippet {{ prop: number }} body - Customize the paragraph text.
   */

  let { prop = 0, children, title, body } = $props();
</script>

<h1>
  {@render children?.({ prop, doubled: prop * 2 })}
  {@render title?.()}
</h1>

<p>
  {@render body?.({ prop })}
</p>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * @slot {{ prop: number; doubled: number; }}
   * @slot {{}} title
   * @slot {{ prop: number }} body - Customize the paragraph text.
   */

  export let prop = 0;
</script>

<h1>
  <slot {prop} doubled={prop * 2} />
  <slot name="title" />
</h1>

<p>
  <slot name="body" {prop} />
</p>
```

</details>

#### Extra JSDoc tags before `@slot`

Tags such as `@example`, `@see`, or `@since` that appear after the prose description and before the `@slot` / `@snippet` line are copied into generated `.d.ts` files. The emitted JSDoc above each slot's snippet prop (and the traditional `SlotDefs` shape) lists the description, then those tags in source order. The same entries appear in JSON as `tags: [{ "name", "body" }, ...]`.

`@deprecated` is handled separately from passthrough slot tags. It fills the slot's `deprecated` JSON field, adds a Markdown badge, and emits `@deprecated` in the `.d.ts`. See [@deprecated](#deprecated).

Put `@slot` / `@snippet` last in the block (description, optional extra tags, slot tag). Tags after `@slot` / `@snippet` in the same comment are not tied to that slot. Unknown tag names pass through as-is. Markdown docs render the description and these tags in the slot's **Description** column (newlines and tag boundaries become `<br />`), alongside TypeScript hover and JSON.

**Example (default slot with `@example` and `@deprecated`):**

````svelte
<script>
  /**
   * Spread `props` onto a custom element.
   * @example
   * ```svelte
   * <Item let:props>
   *   <a {...props} href="/">Home</a>
   * </Item>
   * ```
   * @deprecated Prefer the `link` snippet.
   * @slot {{ props?: { class: string } }}
   */
</script>

<slot props={{ class: "bx--link" }} />
````

#### Svelte 5 Snippet Compatibility

For Svelte 5, `sveld` generates optional snippet props for all slots so consumers can use traditional slot syntax or `{#snippet}`.

When parsing runes components, `sveld` maps `{@render ...}` calls back into the same slot metadata used for `<slot>`. Reserved snippet props like `children`, plus named snippet props from `{@render ...}`, live in `slots` metadata and generated snippet prop types, not duplicated in `props`.

Positional snippet calls like `{@render row?.(item, index)}` stay typed props when the prop has an explicit type like `Snippet<[Item, number]>`. They are not turned into synthetic slot metadata.

For slots with props (e.g., `let:prop`), the generated type uses a Snippet-compatible signature:

```ts
slotName?: (this: void, ...args: [{ prop: PropType }]) => void;
```

For slots without props:

```ts
slotName?: (this: void) => void;
```

**Why this signature?**

- **`this: void`** blocks calling the snippet with a `this` context, matching Svelte's rule that snippets are pure render functions
- **`...args: [Props]`** uses tuple spread for type-safe parameters. It accepts fixed-length tuples (like `[{ row: Row }]`) and rejects array types (like `Props[]`), matching Svelte's `Snippet<T>` type

**Default slot (`children` prop):**

The default slot generates an optional `children` snippet prop:

```svelte
<!-- Component with default slot that passes props -->
<Dropdown {items} selectedId="1">
  {#snippet children({ item, index })}
    <span>{item.text} (#{index})</span>
  {/snippet}
</Dropdown>
```

Generated types:

```ts
type DropdownProps = {
  items: Item[];
  selectedId?: string;

  // Default slot as children snippet prop
  children?: (this: void, ...args: [{ item: Item; index: number }]) => void;
};
```

**Named slots:**

```svelte
<!-- Using the generated types with Svelte 5 syntax -->
<DataTable headers={headers} rows={rows}>
  {#snippet cell({ cell, row })}
    {#if cell.key === 'actions'}
      <Button on:click={() => handleAction(row)}>Edit</Button>
    {:else}
      {cell.value}
    {/if}
  {/snippet}
</DataTable>
```

Generated output includes both the snippet prop and the traditional slot definition:

```ts
type DataTableProps<Row> = {
  // ... other props

  // Snippet prop for Svelte 5 compatibility
  cell?: (
    this: void,
    ...args: [
      {
        row: Row;
        cell: DataTableCell<Row>;
        rowIndex: number;
        cellIndex: number;
      },
    ]
  ) => void;

  // Default slot as children prop
  children?: (this: void) => void;
};

export default class DataTable<Row> extends SvelteComponentTyped<
  DataTableProps<Row>,
  {
    /* events */
  },
  {
    // Traditional slot definition (Svelte 3/4)
    default: Record<string, never>;
    cell: {
      row: Row;
      cell: DataTableCell<Row>;
      rowIndex: number;
      cellIndex: number;
    };
  }
> {}
```

### `@event`

Use the `@event` tag to type dispatched events. An event name is required and a description optional.

In Svelte 5 runes components, callback props like `onclick` are props, not events. The `events` output stays reserved for dispatched events and legacy forwarded events. If a runes component documents `@event foo` and exposes a matching callback prop like `onfoo` without actually dispatching or forwarding `foo`, `sveld` aliases that documentation onto the callback prop instead of synthesizing an emitted event.

Use `null` as the value if no event detail is provided.

**Signature:**

```js
/**
 * Optional event description
 * @event {EventDetail} eventname [inline description]
 */
```

**Example:**

```svelte
<script>
  /**
   * Fired when a value is saved.
   * @event {{ id: string }} save
   */
  let { onsave } = $props();
</script>

<button onclick={() => onsave?.({ id: "1" })}>Save</button>
```

**Svelte 5 Runes with dispatched events:**

```svelte
<script>
  /**
   * @event {{ key: string }} button:key
   * @event {null} key - Fired when `key` changes.
   */

  let { key = "" } = $props();

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  $effect(() => {
    dispatch("button:key", { key });
    if (key) dispatch("key");
  });
</script>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * @event {{ key: string }} button:key
   * @event {null} key - Fired when `key` changes.
   */

  export let key = "";

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  $: dispatch("button:key", { key });
  $: if (key) dispatch("key");
</script>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export default class Component extends SvelteComponentTyped<
  ComponentProps,
  {
    "button:key": CustomEvent<{ key: string }>;
    /** Fired when `key` changes. */ key: CustomEvent<null>;
  },
  Record<string, never>
> {}
```

#### Detail inference without `@event`

Without an `@event` tag or a typed dispatcher, `sveld` infers a dispatched event's detail type from the `dispatch()` call site itself:

- A scalar literal argument narrows to its literal type: `dispatch("count", 5)` types the detail as `5`, not `number`. Use `@event` or a typed dispatcher (below) to widen it.
- An object or array literal argument infers a structural type per field/element: `dispatch("save", { id })` types the detail as `{ id: string }` (resolving the `id` variable's own type), and `dispatch("items", [1, 2])` types it as `number[]`. Fields or elements sveld can't resolve fall back to `any` individually, not for the whole detail.

#### Typed dispatchers

`createEventDispatcher<T>()`'s generic argument (`lang="ts"`, or the JSDoc `/** @type {import('svelte').EventDispatcher<T>} */` cast form) works like an `@event` block for every member of `T`, including ones never actually dispatched in the file:

```svelte
<script lang="ts">
  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher<{ save: { id: string }; cancel: null }>();
</script>
```

`T` may also be a reference to a local `type`/`interface`. An `@event` tag for the same name still overrides the generic's detail type.

#### Using `@property` for complex event details

For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description. See the [`@property`](#property) reference for the tag's valid contexts.

This is the idiomatic way to describe each field of an event detail. An inline object literal such as `@event {{ items: string[]; added: string[] }} change` types the payload but cannot carry per-field descriptions, since a nested block comment would terminate the host JSDoc. Declare the detail with `@type {object}` and `@property` instead to document every field.

**Signature:**

```js
/**
 * Event description
 * @event eventname
 * @type {object}
 * @property {Type} propertyName - Property description
 */
```

**Example:**

```svelte
<script>
  /**
   * Fired when the user submits the form
   *
   * @event submit
   * @type {object}
   * @property {string} name - The user's name
   * @property {string} email - The user's email address
   * @property {boolean} newsletter - Whether the user opted into the newsletter
   */

  let { name = "Jane Doe", email = "jane@example.com", newsletter = true } = $props();

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  function handleSubmit() {
    dispatch("submit", { name, email, newsletter });
  }
</script>

<button type="button" onclick={handleSubmit}>Submit</button>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Fired when the user submits the form
   *
   * @event submit
   * @type {object}
   * @property {string} name - The user's name
   * @property {string} email - The user's email address
   * @property {boolean} newsletter - Whether the user opted into the newsletter
   */

  export let name = "Jane Doe";
  export let email = "jane@example.com";
  export let newsletter = true;

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  function handleSubmit() {
    dispatch("submit", { name, email, newsletter });
  }
</script>

<button type="button" on:click={handleSubmit}>Submit</button>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export default class Component extends SvelteComponentTyped<
  ComponentProps,
  {
    /** Fired when the user submits the form */
    submit: CustomEvent<{
      /** The user's name */
      name: string;
      /** The user's email address */
      email: string;
      /** Whether the user opted into the newsletter */
      newsletter: boolean;
    }>;
  },
  Record<string, never>
> {}
```

#### Optional properties in event details

Like typedefs, you can mark event detail properties as optional with square brackets when they are not always in the payload.

**Example:**

```svelte
<script>
  /**
   * Snowball event fired when throwing a snowball
   *
   * @event snowball
   * @type {object}
   * @property {boolean} isPacked - Indicates whether the snowball is tightly packed
   * @property {number} speed - The speed of the snowball in mph
   * @property {string} [color] - Optional color of the snowball
   * @property {number} [density=0.9] - Optional density with default value
   */

  let { speed = 50 } = $props();

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  function throwSnowball() {
    dispatch("snowball", {
      isPacked: true,
      speed,
    });
  }
</script>

<button type="button" onclick={throwSnowball}>Throw</button>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * Snowball event fired when throwing a snowball
   *
   * @event snowball
   * @type {object}
   * @property {boolean} isPacked - Indicates whether the snowball is tightly packed
   * @property {number} speed - The speed of the snowball in mph
   * @property {string} [color] - Optional color of the snowball
   * @property {number} [density=0.9] - Optional density with default value
   */

  export let speed = 50;

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();

  function throwSnowball() {
    dispatch("snowball", {
      isPacked: true,
      speed,
    });
  }
</script>

<button type="button" on:click={throwSnowball}>Throw</button>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export default class Component extends SvelteComponentTyped<
  ComponentProps,
  {
    /** Snowball event fired when throwing a snowball */
    snowball: CustomEvent<{
      /** Indicates whether the snowball is tightly packed */
      isPacked: boolean;
      /** The speed of the snowball in mph */
      speed: number;
      /** Optional color of the snowball */
      color?: string;
      /** Optional density with default value @default 0.9 */
      density?: number;
    }>;
  },
  Record<string, never>
> {}
```

#### Discriminated unions in event details

When the event detail is a union (or any non-object shape), use `@type` to declare it directly. An explicit `@type` wins over `@property` tags, so the union is copied verbatim into the emitted `.d.ts` instead of being flattened into independent property unions. The only exception is `@type {object}`, which tells `sveld` to build the shape from `@property` tags (as shown above).

**Example:**

```svelte
<script>
  /**
   * @event sort
   * @type {{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }}
   * Dispatched when a sortable column header would change the active sort.
   */

  import { createEventDispatcher } from "svelte";

  const dispatch = createEventDispatcher();
</script>
```

Output:

```ts
export default class Component extends SvelteComponentTyped<
  ComponentProps,
  {
    /** Dispatched when a sortable column header would change the active sort. */
    sort: CustomEvent<{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }>;
  },
  Record<string, never>
> {}
```

Any free-text prose after the tags is attached to the event description, not to a property doc.

### `@ignore` / `@internal`

`@ignore` and `@internal` are equivalent aliases: either one excludes a prop, event, slot, typedef, module export, entry export, or context from every output — JSON, Markdown, `.d.ts`, and the Custom Elements Manifest. Use them for implementation details that would otherwise leak into the public API docs.

The tag's position mirrors [`@deprecated`](#deprecated): before `@slot`/`@snippet`/`@typedef`/`@callback`, alongside the description, and after the `@event` line.

```svelte
<script>
  /** The visible label. */
  export let label = "";

  /**
   * Implementation detail; not part of the public API.
   * @internal
   */
  export let debugId = "";

  /**
   * Fired when the value changes.
   * @event {{ value: string }} change
   */

  /**
   * Fired for internal diagnostics only.
   * @event {{ reason: string }} debug
   * @internal
   */

  /**
   * @internal
   * @slot {{}} debug-panel
   */
</script>
```

`debugId`, the `debug` event, and the `debug-panel` slot never appear in `COMPONENT_INDEX.md`, `COMPONENT_API.json`, the generated `.d.ts`, or the Custom Elements Manifest — as if they were never declared. Internally, the parser still records them (with an `internal: true` flag) on the raw parsed component; only `buildComponentApiDocument` — the shared step every writer runs through — filters them out, so a custom writer built on the raw parse result can still see them if it chooses to.

For a context (`setContext(key, value)`), tag the JSDoc on the *value* variable, the same place its type annotation and description already live:

```svelte
<script>
  /**
   * @type {{ token: string }}
   * @internal
   */
  let authContext = { token: "" };

  setContext("auth", authContext);
</script>
```

A whole inline object literal passed directly to `setContext` (no intermediate variable) has no JSDoc position of its own, so `@internal` isn't supported there. An individual property *inside* one can be marked `@internal`, though, as long as its value is an identifier carrying its own JSDoc:

```svelte
<script>
  /**
   * @type {string}
   * @internal
   */
  let debugToken = "";

  let publicUser = { name: "" };

  setContext("session", { user: publicUser, debug: debugToken });
</script>
```

Only the `debug` property is excluded from `session`'s generated shape; `user` and the context itself are unaffected.

Because an internal member never appears in output, adding `@internal` to a previously-public prop, event, slot, or typedef is a breaking change for `--check` purposes (it disappears from the generated `.d.ts` just like an outright removal). Removing an already-`@internal` member, by contrast, is not breaking — it was never part of the committed public snapshot to begin with.

### `@deprecated`

Add `@deprecated` to a prop, event, slot, entry export, or exported accessor. An optional message after the tag can explain why or name a replacement.

```svelte
<script>
  /**
   * The visible label.
   * @deprecated Use the `text` prop instead.
   */
  export let label = "";

  /**
   * Programmatically focus the field.
   * @deprecated Focus the underlying element directly.
   */
  export function focus() {}

  /**
   * @event {{ value: string }} change
   * @deprecated Listen for the native `input` event instead.
   */

  /**
   * Badge content rendered next to the label.
   * @deprecated Render the badge inline instead.
   * @slot {{ count: number }} badge
   */
</script>
```

For slots, put `@deprecated` before the `@slot` / `@snippet` line, alongside the description and any other [extra tags](#extra-jsdoc-tags-before-slot). For events, put it after the `@event` line. For entry exports (see [Documenting Entry Exports](#documenting-entry-exports)), put it in the JSDoc directly above the `const`/`function`/`class`/`type`/`interface` declaration, same as a prop.

Generated `.d.ts` files include an `@deprecated` JSDoc line so editors strike the symbol through. JSON adds a `deprecated` field (the message string, or `true` when the tag has no message). Markdown strikes through the name and adds a **Deprecated** badge with the message when present.

```ts
/**
 * The visible label.
 * @deprecated Use the `text` prop instead.
 */
label?: string;
```

```json
{ "name": "label", "deprecated": "Use the `text` prop instead." }
```

### `@since`

`@since` records the version a prop, event, or slot was introduced. `sveld` does not validate or parse the version text — whatever follows the tag is copied through as-is.

**Valid contexts:**

- **Prop / module export** — captured as a structured tag: JSON adds a `tags: [{ "name": "since", "body": "..." }]` array on the prop (kept separate from `description`), the generated `.d.ts` emits `@since ...` as its own JSDoc line above `@default`, and the Markdown table's Description column appends `@since ...` after the description, same as slots.
- **`@event`** — same structured behavior as props, but only when `@since` is placed **after** the `@event` line in the same comment block (matching the [`@deprecated`](#deprecated) rule for events). Placed before `@event`, it is silently dropped.
- **`@slot` / `@snippet`** — placed before the `@slot`/`@snippet` line, alongside the description. Fully surfaced in JSON, `.d.ts`, *and* the Markdown table. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
- **`@typedef`** — **not supported.** A `@since` before `@typedef` produces no output anywhere; it is silently dropped.
- **`@component` comments** — passed through verbatim as part of the raw HTML comment text. See [@component comments](#component-comments).

**Example:**

```svelte
<script>
  /**
   * A width prop.
   * @since 1.2.0
   * @type {number}
   */
  let { width = 0 } = $props();
</script>
```

Output (`.d.ts`):

```ts
export type ScratchProps = {
  /**
   * A width prop.
   * @since 1.2.0
   * @default 0
   */
  width?: number;
};
```

Output (JSON, relevant slice):

```json
{ "name": "width", "description": "A width prop.", "tags": [{ "name": "since", "body": "1.2.0" }] }
```

Output (Markdown props table Description column):

```
A width prop.<br />@since 1.2.0
```

### `@see`

`@see` adds a reference link or citation. Like `@since`, `sveld` does not resolve or validate the target — it is free text.

**Valid contexts:**

- **Prop / module export** — `@see` is *not* one of the small set of tags `sveld` structures specially, so it is folded verbatim into the prop's `description` as an extra line (`@see ...`) rather than getting its own `tags` entry. Because it lives in `description`, it *does* show up everywhere `description` is used: JSON, `.d.ts`, and the Markdown table.
- **`@event`** — **not supported in either position** (before or after `@event`). A `@see` tag near an `@event` block is silently dropped in both JSON and `.d.ts`.
- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`, alongside the description: fully supported in JSON, `.d.ts`, and Markdown, same as `@since`. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
- **`@typedef`** — **not supported.** Dropped silently, same as `@since`.
- **`@component` comments** — passed through verbatim, same as `@since`.

**Example:**

```svelte
<script>
  /**
   * A width prop.
   * @see https://example.com/width-docs
   * @type {number}
   */
  let { width = 0 } = $props();
</script>
```

Output (`.d.ts`):

```ts
export type ScratchProps = {
  /**
   * A width prop.
   * @see https://example.com/width-docs
   * @default 0
   */
  width?: number;
};
```

Output (Markdown props table Description column):

```
A width prop.<br />@see https://example.com/width-docs
```

### `@link`

`{@link target}` (optionally `{@link target|display text}`) is an inline JSDoc tag used inside prose, not a block-level tag like the others on this page. `sveld`'s comment parser only treats a *line* as starting a new tag when it begins with `@` — `{@link ...}` always starts with `{`, so it's never intercepted. It is always literal text.

**Valid contexts:** anywhere free-form description text is read — prop and module export descriptions, event descriptions, slot descriptions, entry export descriptions, typedef descriptions, `@component` HTML comments, and `@example` bodies. `sveld` never resolves or validates the target. JSON `description` and `.d.ts` JSDoc always keep the tag verbatim. **Markdown is the one exception:** in a prop, event, slot, or entry export's Description table cell, `{@link target|text}` / `{@link target}` is rewritten to a Markdown link, `[text](target)` / `[target](target)`. Typedef descriptions (rendered as a `.d.ts`-style code block) and `@component` comments keep the tag literal in Markdown too, since neither goes through the table-cell renderer.

**Example:**

```svelte
<script>
  /**
   * The element's width in pixels. See {@link https://example.com/width|width docs}.
   * @type {number}
   */
  let { width = 0 } = $props();
</script>
```

Output (`.d.ts`):

```ts
export type ScratchProps = {
  /**
   * The element's width in pixels. See {@link https://example.com/width|width docs}.
   * @default 0
   */
  width?: number;
};
```

The same literal string appears unchanged in JSON `description`. The Markdown table's Description column instead shows: `The element's width in pixels. See [width docs](https://example.com/width).`

### `@example`

`@example` has two related uses: as a plain JSDoc tag whose body is copied into generated output, and — with `checkExamples: true` — as input to sveld's compile-checker for plain TS/JS example code. This section covers the tag itself; see [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples) for the type-checking feature.

`@example` shares its underlying mechanism with `@since` (both are in the small set of tags `sveld` treats as structured "IDE passthrough" tags), so the valid contexts are the same:

- **Prop / module export (including functions)** — structured `tags` entry in JSON, its own `@example` block in `.d.ts`, and appended to the Markdown table's Description column, same as `@since`.
- **`@event`** — only when placed **after** the `@event` line in the same block, same rule as `@since`.
- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`: fully supported in JSON, `.d.ts`, and Markdown. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
- **`@typedef`** — **not supported**, dropped silently, same as `@since`.
- **`@component` comments** — passed through verbatim; this is already how the [`@component` comments](#component-comments) example on this page uses `@example`.

**Example:**

```svelte
<script>
  /**
   * Formats a value.
   * @param {string} value
   * @returns {string}
   * @example
   * ```js
   * formatValue("ok");
   * ```
   */
  export function formatValue(value) {
    return value;
  }
</script>
```

Output (`.d.ts`):

```ts
/**
 * Formats a value.
 * @example
 *  ```js
 *  formatValue("ok");
 *  ```
 */
formatValue: (value: string) => string;
```

`@param`/`@returns` are consumed into the function's type signature rather than kept as separate JSDoc lines.

Output (Markdown props table Description column, newlines rendered as `<br />`):

````
Formats a value.<br />@example ```js<br /> formatValue("ok");<br /> ```
````

### Context API

`sveld` generates TypeScript definitions for Svelte's `setContext`/`getContext` by extracting types from JSDoc on context values.

#### How it works

When you call `setContext` in a component, `sveld`:

1. Detects the `setContext` call
2. Resolves the context key (see [Supported context keys](#supported-context-keys))
3. Finds JSDoc `@type` annotations on the variables being passed
4. Generates a TypeScript type export for the context

#### Supported context keys

The key becomes the `{PascalCase}Context` type name. `sveld` can resolve:

| Key form | Example | Generated type |
| --- | --- | --- |
| String literal | `setContext("simple-modal", …)` | `SimpleModalContext` |
| Static template literal | `` setContext(`simple-modal`, …) `` | `SimpleModalContext` |
| `const`-bound string | `const KEY = "simple-modal";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
| `Symbol()` / `Symbol.for()` | `setContext(Symbol("tabs"), …)` | `TabsContext` |

`const` identifiers are followed up to 5 levels deep (`const A = "x"; const B = A;`). Only `const` bindings count. `let`, `var`, and props are skipped because they can change at runtime.

Symbol keys take their name from the description: `Symbol("tabs")` and `Symbol.for("tabs")` both become `TabsContext`. For `const ModalKey = Symbol()` with no description, the binding name wins: `ModalKeyContext`.

Anything else (dynamic identifiers, template interpolation, other function calls) logs a warning. No context type is generated.

#### Example

**Modal.svelte**

```svelte
<script>
  import { setContext } from "svelte";

  /**
   * Close the modal
   * @type {() => void}
   */
  const close = () => {
    // Close logic
  };

  /**
   * Open the modal with content
   * @type {(component: any, props?: any) => void}
   */
  const open = (component, props) => {
    // Open logic
  };

  setContext("simple-modal", { open, close });

  let { children } = $props();
</script>

<div class="modal">
  {@render children?.()}
</div>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  import { setContext } from "svelte";

  /**
   * Close the modal
   * @type {() => void}
   */
  const close = () => {
    // Close logic
  };

  /**
   * Open the modal with content
   * @type {(component: any, props?: any) => void}
   */
  const open = (component, props) => {
    // Open logic
  };

  setContext("simple-modal", { open, close });
</script>

<div class="modal">
  <slot />
</div>
```

</details>

Output is identical for both syntax modes.

**Generated TypeScript definition:**

```ts
export type SimpleModalContext = {
  /** Open the modal with content */
  open: (component: any, props?: any) => void;
  /** Close the modal */
  close: () => void;
};

export type ModalProps = {};

export default class Modal extends SvelteComponentTyped<
  ModalProps,
  Record<string, any>,
  { default: Record<string, never> }
> {}
```

**Consumer usage:**

```svelte
<script>
  import { getContext } from 'svelte';
  import type { SimpleModalContext } from 'modal-library/Modal.svelte';

  const { close, open } = getContext<SimpleModalContext>('simple-modal');
</script>

<button on:click={close}>Close</button>
```

#### Explicitly typing contexts

There are several ways to type contexts:

**Option 1: Inline JSDoc on variables (recommended)**

```svelte
<script>
  import { setContext } from 'svelte';

  /**
   * @type {() => void}
   */
  const close = () => {};

  setContext('modal', { close });
</script>
```

**Option 2: Using @typedef for complex types**

```svelte
<script>
  import { setContext } from 'svelte';

  /**
   * @typedef {object} TabData
   * @property {string} id
   * @property {string} label
   * @property {boolean} [disabled]
   */

  /**
   * @type {(tab: TabData) => void}
   */
  const addTab = (tab) => {};

  setContext('tabs', { addTab });
</script>
```

**Option 3: Referencing imported types**

```svelte
<script>
  import { setContext } from 'svelte';

  /**
   * @type {typeof import("./types").ModalAPI}
   */
  const modalAPI = {
    open: () => {},
    close: () => {}
  };

  setContext('modal', modalAPI);
</script>
```

**Option 4: Direct object literal with inline functions**

```svelte
<script>
  import { setContext } from 'svelte';

  // sveld infers basic function signatures
  setContext('modal', {
    open: (component, props) => {}, // Inferred as (arg, arg) => any
    close: () => {}                 // Inferred as () => any
  });
</script>
```

> Inline functions without `@type` annotations get generic inferred signatures. Add explicit JSDoc when you care about the shape.

#### Notes

- Context keys must be statically resolvable: a string literal, a static template literal, a `const`-bound string, or a `Symbol()` / `Symbol.for()` call with a static description. Dynamic expressions (runtime identifiers, template interpolation, other function calls) are skipped with a warning.
- Variables passed to `setContext` should have JSDoc `@type` annotations for accurate types
- The generated type name follows the pattern: `{PascalCase}Context`. Separators (hyphens, underscores, dots, colons, slashes, spaces) are stripped and each segment is capitalized:
  | Context Key | Generated Type Name |
  | --- | --- |
  | `"simple-modal"` | `SimpleModalContext` |
  | `"user_settings"` | `UserSettingsContext` |
  | `"Carbon.Modal"` | `CarbonModalContext` |
  | `"Carbon:Modal"` | `CarbonModalContext` |
  | `"app/modal"` | `AppModalContext` |
  | `"My Context"` | `MyContextContext` |
  | `"Tabs"` | `TabsContext` |
- If no type annotation is found, the type defaults to `any` with a warning

### `@restProps`

`sveld` can detect inline HTML elements that `$$restProps` is forwarded to. It cannot infer the underlying element for instantiated components.

Use `@restProps` to name the element tags `$$restProps` is forwarded to.

**Signature:**

```js
/**
 * Single element
 * @restProps {tagname}
 *
 * Multiple elements
 * @restProps {tagname-1 | tagname-2 | tagname-3}
 */
```

**Example:**

```svelte
<script>
  import Button from "./Button.svelte";

  /** @restProps {h1 | button} */
  let { edit = false, children, ...restProps } = $props();
</script>

{#if edit}
  <Button {...restProps} />
{:else}
  <h1 {...restProps}>
    {@render children?.()}
  </h1>
{/if}
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /** @restProps {h1 | button} */
  export let edit = false;

  import Button from "./Button.svelte";
</script>

{#if edit}
  <Button {...$$restProps} />
{:else}
  <h1 {...$$restProps}><slot /></h1>
{/if}
```

</details>

### `@extendProps`

When a component wraps another, use `@extendProps` to extend generated props.

> `@extends` works as an alias, but prefer `@extendProps` to avoid clashing with standard JSDoc `@extends` for class inheritance.

**Signature:**

```js
/**
 * @extendProps {<relative path to component>} ComponentProps
 */
```

**Example:**

```js
/** @extendProps {"./Button.svelte"} ButtonProps */

export const secondary = true;

import Button from "./Button.svelte";
```

The named interface must match the target's generated props type name exactly — the default `<Name>Props`, or whatever [`typesOptions.typeNames`](#typesoptionstypenames) templates it to.

### `@template`

Svelte supports defining generics via the [`generics` attribute](https://svelte.dev/docs/svelte/typescript) on the script tag, but this requires `lang="ts"`:

```svelte
<script lang="ts" generics="Row extends DataTableRow = any"></script>
```

`sveld` reads the `generics` attribute directly, and it's the recommended way to declare generics for `lang="ts"` components. Because `sveld` also targets JavaScript-only usage as a baseline, plain JS (or JS-with-JSDoc) components instead use the standard JSDoc `@template` tag; `@generics` is also supported as an alias.

**Precedence:** if a component declares generics both ways, the `generics` attribute wins — it's the compiler-checked source of truth — and the `@generics`/`@template` tag is reported as a `syntax-skipped` diagnostic rather than silently dropped. The attribute is invalid without `lang="ts"`; if present on a plain-JS script, sveld reports `syntax-skipped` and ignores it rather than guessing.

**Signature:** Uses standard [JSDoc `@template` syntax](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template):

```js
/**
 * @template {Constraint} [Name=Default]
 */
```

**Example:**

```js
/**
 * @template {DataTableRow} [Row=DataTableRow]
 */
```

**Component example:**

```svelte
<script>
  /**
   * @typedef {{ id: string | number; [key: string]: any; }} DataTableRow
   * @typedef {Exclude<keyof Row, "id">} DataTableKey<Row>
   * @typedef {{ key: DataTableKey<Row>; value: string; }} DataTableHeader<Row=DataTableRow>
   * @template {DataTableRow} [Row=DataTableRow]
   */

  let {
    /** @type {ReadonlyArray<DataTableHeader<Row>>} */
    headers = [],
    /** @type {ReadonlyArray<Row>} */
    rows = [],
    children,
  } = $props();
</script>

{@render children?.({ headers, rows })}
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * @typedef {{ id: string | number; [key: string]: any; }} DataTableRow
   * @typedef {Exclude<keyof Row, "id">} DataTableKey<Row>
   * @typedef {{ key: DataTableKey<Row>; value: string; }} DataTableHeader<Row=DataTableRow>
   * @template {DataTableRow} [Row=DataTableRow]
   */

  /** @type {ReadonlyArray<DataTableHeader<Row>>} */
  export let headers = [];

  /** @type {ReadonlyArray<Row>} */
  export let rows = [];
</script>

<slot {headers} {rows} />
```

</details>

Output is identical for both syntax modes.

Generated output looks like this:

```ts
export type ComponentProps<Row extends DataTableRow = DataTableRow> = {
  headers?: ReadonlyArray<DataTableHeader<Row>>;
  rows?: ReadonlyArray<Row>;
};

export default class Component<
  Row extends DataTableRow = DataTableRow,
> extends SvelteComponentTyped<
  ComponentProps<Row>,
  Record<string, any>,
  Record<string, any>
> {}
```

For multiple generics, use separate `@template` tags:

```js
/**
 * @template {DataTableRow} [Row=DataTableRow]
 * @template {DataTableRow} [Header=DataTableRow]
 */
```

```ts
export type ComponentProps<
  Row extends DataTableRow = DataTableRow,
  Header extends DataTableRow = DataTableRow,
> = { ... };

export default class Component<
  Row extends DataTableRow = DataTableRow,
  Header extends DataTableRow = DataTableRow,
> extends SvelteComponentTyped<
  ComponentProps<Row, Header>,
  Record<string, any>,
  Record<string, any>
> {}
```

### `@generics`

As an alternative to `@template`, sveld supports `@generics`. Unlike `@template`, which [JSDoc/TypeScript support officially](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template), `@generics` is sveld-specific. The syntax can be easier to read because the full constraint is inline:

```js
/**
 * @generics {Row extends DataTableRow = DataTableRow} Row
 */
```

This is equivalent to:

```js
/**
 * @template {DataTableRow} [Row=DataTableRow]
 */
```

For multiple generics, use a single `@generics` tag with comma-separated names:

```js
/**
 * @generics {Row extends DataTableRow = DataTableRow, Header extends DataTableRow = DataTableRow} Row,Header
 */
```

### `@component` comments

The Svelte Language Server supports component-level comments through the following syntax: `<!-- @component [comment] -->`.

`sveld` copies these over to the exported default component in the TypeScript definition.

**Example:**

```svelte
<!-- @component
@example
<Button>
  Text
</Button>
-->
<script>
  let { children } = $props();
</script>

<button>
  {@render children?.()}
</button>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<!-- @component
@example
<Button>
  Text
</Button>
-->
<button>
  <slot />
</button>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
/**
 * @example
 * <Button>
 *   Text
 * </Button>
 */
export default class Button extends SvelteComponentTyped<
  ButtonProps,
  Record<string, any>,
  { default: Record<string, never> }
> {}
```

### Accessor Props

Exported functions and consts become accessor props in generated TypeScript definitions. Use `@type` for function signatures, or `@param` and `@returns` (or `@return`) for richer docs.

`@type` wins over `@param`/`@returns` when both are present.

**Signature:**

```js
/**
 * Function description
 * @param {Type} paramName - Parameter description
 * @param {Type} [optionalParam] - Optional parameter
 * @returns {ReturnType} Return value description
 */
```

**Example:**

```svelte
<script>
  /**
   * @typedef {object} NotificationData
   * @property {string} [id] - Optional id for deduplication
   * @property {"error" | "info" | "success"} [kind]
   */

  let { children } = $props();

  /**
   * Add a notification to the queue.
   * @param {NotificationData} notification
   * @returns {string} The notification id
   */
  export function add(notification) {
    const id = notification.id ?? "id";
    return id;
  }

  /**
   * Remove a notification by id.
   * @param {string} id
   * @returns {boolean} True if the notification was found and removed
   */
  export function remove(id) {
    return true;
  }

  /**
   * Get notification count.
   * @returns {number} The number of notifications
   */
  export function getCount() {
    return 0;
  }
</script>

<div>
  {@render children?.()}
</div>
```

<details>
<summary>Svelte 3/4 (legacy) syntax</summary>

```svelte
<script>
  /**
   * @typedef {object} NotificationData
   * @property {string} [id] - Optional id for deduplication
   * @property {"error" | "info" | "success"} [kind]
   */

  /**
   * Add a notification to the queue.
   * @param {NotificationData} notification
   * @returns {string} The notification id
   */
  export function add(notification) {
    const id = notification.id ?? "id";
    return id;
  }

  /**
   * Remove a notification by id.
   * @param {string} id
   * @returns {boolean} True if the notification was found and removed
   */
  export function remove(id) {
    return true;
  }

  /**
   * Get notification count.
   * @returns {number} The number of notifications
   */
  export function getCount() {
    return 0;
  }
</script>
```

</details>

Output is identical for both syntax modes.

Output:

```ts
export type NotificationData = {
  /** Optional id for deduplication */
  id?: string;
  kind?: "error" | "info" | "success";
};

export type ComponentProps = Record<string, never>;

export default class Component extends SvelteComponentTyped<
  ComponentProps,
  Record<string, any>,
  Record<string, never>
> {
  /**
   * Add a notification to the queue.
   */
  add: (notification: NotificationData) => string;

  /**
   * Remove a notification by id.
   */
  remove: (id: string) => boolean;

  /**
   * Get notification count.
   */
  getCount: () => number;
}
```

When only `@param` tags are present without `@returns`, the return type defaults to `any`. When only `@returns` is present without `@param`, the function signature is `() => returnType`.

The Markdown writer marks the same exports (a `const`, or a real function declaration) with Kind `accessor` in the Props table, instead of their raw `const`/`function` kind, matching the `.d.ts` output above.

## Troubleshooting

**A prop came out `any`.** Enable [`reportDiagnostics`](#type-inference-diagnostics) (or `strict` to fail CI) to see which props sveld couldn't infer, then tighten them with `@type` or a native TypeScript annotation.

**Generated types don't appear for consumers.** Check that the `types` folder is listed in `exports` and `files` in `package.json`. See [Publishing to NPM](#publishing-to-npm).

**Output differs in CI.** Commit `COMPONENT_API.json` and run [`--check`](#ci-api-drift-checks---check) in CI so API drift fails the build instead of silently diverging.

**`sveld: cannot resolve "..." from ...`.** An `export *` or a named re-export points at a module or path alias that doesn't resolve to a file on disk. Fix the specifier, or check the tsconfig/jsconfig `paths` entry it's supposed to match. This exits `1`; see [Exit codes](#exit-codes).

**A path alias (`$lib`, `@components`, ...) isn't picked up.** sveld only reads aliases from `compilerOptions.paths` in the nearest `tsconfig.json` or `jsconfig.json`, found by walking up from the file doing the importing. Vite/SvelteKit alias config (`vite.config.*`, `svelte.config.*`) is not read directly — add the same aliases to `paths` so both tools agree. When a pattern has more than one mapping (`"$lib/*": ["./src/lib/*", "./lib/*"]`), sveld tries them in order and uses the first one that exists on disk, falling back to the first mapping if none do; among multiple matching patterns, the one with the longest non-wildcard prefix wins, regardless of declaration order (matching `tsc`).

## Contributing

See [contributing guidelines](CONTRIBUTING.md).

## License

[Apache-2.0](LICENSE)

[npm]: https://img.shields.io/npm/v/sveld.svg?color=262626&style=for-the-badge
[npm-url]: https://npmjs.com/package/sveld