svelte.ts

Svelte component analysis helpers.
Extracts metadata from Svelte components using svelte2tsx transformations:
- Component props with types and JSDoc
- Component-level documentation
- Type information
Workflow: Transform Svelte to TypeScript via svelte2tsx, parse the transformed
TypeScript with the TS Compiler API, extract component-level JSDoc from original source.
Svelte 5 only: The svelte2tsx output format changed significantly between versions.
This module requires Svelte 5+ and will throw a clear error if an older version is detected.
There is no Svelte 4 compatibility layer.
@see typescript-exports.ts for analyzeExports, extractModuleComment
@see typescript-extract-shared.ts for parseGenericParam, filterIntersectionProperties
@see typescript-program.ts for IsExternalFile, createIsExternalFile
@see tsdoc.ts for parseComment, applyToDeclaration
@see source.ts for SourceFileInfo, getComponentName

Declarations
#

11 declarations

view source

analyzeSvelteModule
#

svelte.ts view source

(sourceFile: SourceFileInfo & { dependents?: readonly string[] | undefined; }, modulePath: string, checker: TypeChecker, options: ModuleSourceOptions, diagnostics: ({ ...; } | ... 12 more ... | { ...; })[], program: Program, virtualFile: SvelteVirtualFile): ModuleAnalysis | undefined

Analyze a Svelte module using checker-backed analysis.
Requires the svelte2tsx virtual output to be included in the TypeScript program
(via createAnalysisProgram({ virtualFiles })). Provides full type resolution for:
- Imported prop types (let {x}: ImportedProps = $props())
- <script module> exports (constants, types, re-exports)
- Star exports and re-exports from Svelte files

`sourceFile`

the original Svelte source file

type SourceFileInfo & { dependents?: readonly string[] | undefined; }

`modulePath`

module path relative to source root

type string

`checker`

TypeScript type checker (from the program containing virtual files)

type TypeChecker

`options`

module source options for path extraction

type ModuleSourceOptions

`diagnostics`

diagnostics collector for non-fatal issues

type

({ symbolName: string; file: string; message: string; severity: "error" | "warning"; kind: "type_extraction_failed"; line?: number | undefined; column?: number | undefined; } | { functionName: string; ... 5 more ...; column?: number | undefined; } | ... 11 more ... | { ...; })[]

`program`

TypeScript program containing the virtual file

type Program

`virtualFile`

pre-transformed virtual file data

type SvelteVirtualFile

returns

ModuleAnalysis | undefined

module analysis with declarations, re-exports, and star exports;
undefined if the virtual file is not found in the program

extractHtmlModuleComment
#

svelte.ts view source

(svelteSource: string): string | undefined

Extract @module comment from HTML comments in Svelte source.
Scans all <!-- ... --> comments for one containing @module at the
start of a line. This allows @component and @module to coexist as
separate HTML comments. Works for template-only components.

`svelteSource`

the full Svelte source code

type string

returns

string | undefined

the cleaned module comment text, or undefined if no @module HTML comment found

extractScriptContent
#

svelte.ts view source

(svelteSource: string): string | undefined

Extract the content of the main <script> tag from Svelte source.
Matches <script> with any attributes (e.g., lang, generics) but excludes
module scripts (<script module>, <script context="module">).

`svelteSource`

type string

returns

string | undefined

the script tag content, or undefined if no matching script tag is found

extractSnippetParameters
#

svelte.ts view source

(snippetType: Type, checker: TypeChecker): { name: string; type: string; optional?: boolean | undefined; rest?: boolean | undefined; description?: string | undefined; defaultValue?: string | undefined; }[]

Extract structured parameters from a Snippet<[...]> type.
Snippet is an interface, so type arguments are on TypeReference (accessed
via checker.getTypeArguments), not on aliasTypeArguments (which is only
for type aliases).
Returns full ParameterJson input objects (with optional and rest always set)
for runtime consistency with extractSignatureParameters in typescript-extract-shared.ts.

`snippetType`

type Type

`checker`

type TypeChecker

returns

{ name: string; type: string; optional?: boolean | undefined; rest?: boolean | undefined; description?: string | undefined; defaultValue?: string | undefined; }[]

array of parameter info for the snippet's tuple type arguments,
or [] for bare Snippet / Snippet<[]>

extractSvelteModuleComment
#

svelte.ts view source

(scriptContent: string): string | undefined

Extract module-level comment from Svelte script content.
Parses the script content as TypeScript and delegates to extractModuleComment
for the shared @module tag detection logic.

`scriptContent`

the content of the <script> tag

type string

returns

string | undefined

the cleaned module comment text, or undefined if none found

isSnippetReturnType
#

svelte.ts view source

(returnType: string): boolean

Check if a return type string matches svelte2tsx's snippet return type pattern.
svelte2tsx transforms exported snippets into arrow functions with
ReturnType<import('svelte').Snippet> as the return type annotation.
The resolved return type includes unique symbol (from Svelte's non-exported
SnippetReturn unique symbol) intersected with the branded render message.
We match on both parts to avoid false positives — the branded message alone
could theoretically be crafted by user code, but the unique symbol intersection
cannot since SnippetReturn is not exported from svelte.

`returnType`

type string

returns

boolean

isSnippetTypeString
#

svelte.ts view source

(typeString: string): boolean

Check if a type string represents a Snippet type.
Uses the already-resolved type string (from checker.typeToString) for reliable
detection. Snippet is an interface (not a type alias), so aliasSymbol is
not available — type string matching is the reliable detection path.

`typeString`

type string

returns

boolean

SvelteVirtualFile
#

svelte.ts view source

SvelteVirtualFile

Pre-transformed Svelte virtual file data.
Produced by transformSvelteSource and consumed by analyzeSvelteModule
to provide checker-backed analysis of Svelte components.

`virtualPath`

Path used for the virtual file in the TypeScript program.

type string

`content`

svelte2tsx transformed TypeScript content.

type string

`sourceMap`

Source map for position mapping back to the original .svelte file.

type SourceMap | null

`lang`

Script language. undefined means TypeScript (default), 'js' for JavaScript-only components.

type 'js' | undefined

synthesizeSnippetTypeSignature
#

svelte.ts view source

(parameters: { name: string; type: string; optional?: boolean | undefined; rest?: boolean | undefined; description?: string | undefined; defaultValue?: string | undefined; }[]): string

Synthesize a Snippet<[...]> type string from structured parameters.
Used for kind: 'snippet' declarations where the raw svelte2tsx type
is implementation noise. Produces type strings consistent with how
the checker formats Snippet types on props.

`parameters`

type

{ name: string; type: string; optional?: boolean | undefined; rest?: boolean | undefined; description?: string | undefined; defaultValue?: string | undefined; }[]

returns

string

TransformResult
#

svelte.ts view source

TransformResult

Result of transformSvelteSource — a virtual file (when transform succeeded)
plus any ingest-time diagnostics produced during the transform.
virtual is undefined when svelte2tsx threw; in that case diagnostics
contains a transform_failed entry. When the transform succeeded but source
map construction failed, virtual is populated and diagnostics contains a
source_map_failed entry. The session's owned-entry stores both — the
virtual (or transformFailed: true flag) and the ingest diagnostics.

`virtual`

type SvelteVirtualFile | undefined

`diagnostics`

type Array<Diagnostic>

transformSvelteSource
#

svelte.ts view source

(sourceFile: SourceFileInfo): TransformResult

Pre-transform a Svelte source file via svelte2tsx.
Produces a SvelteVirtualFile containing the transformed TypeScript content
and source map. The virtual file can be included in a TypeScript program
(via createAnalysisProgram({ virtualFiles })) so that the checker can
resolve imported types, <script module> exports, and re-exports.
Errors at ingest are returned via diagnostics rather than thrown:
- svelte2tsx throws → transform_failed, virtual: undefined
- source map construction fails → source_map_failed, virtual populated
Diagnostic file paths are the original .svelte source ID; downstream
normalization rewrites them to project-root-relative form.

`sourceFile`

the Svelte source file with content loaded

type SourceFileInfo

returns

TransformResult

virtual file data (or undefined on transform failure) plus ingest diagnostics

throws

Error - if Svelte version is below 5 (checked once on first call)