Published as svelte-docinfo to npm:

There are several ways to get the JSON, from most opinionated to most flexible.

For SvelteKit and Vite projects, the Vite plugin is the recommended path. It runs the analysis at build time and serves the result as a virtual module that stays current in dev:

Run the CLI to inspect a project from the command line:

For standalone use or custom build tools, two functions cover most cases. analyzeFromFiles discovers files for you:

If your build tool already has file contents in memory, analyze skips discovery. See the build tools guide:

For long-lived consumers that re-analyze the same source set (Vite plugin, LSP-style tools), createAnalysisSession returns a persistent handle that reuses parsed ASTs and svelte2tsx output across calls. See the session guide.

See the API reference for all exported functions and types.

Standalone namespace Foo {} declarations document as a bare variable with no members (namespace re-exports are supported). Decorators aren't modeled.

Svelte 4 features like slots are not supported. Legacy export let props aren't extracted, but a legacy_props warning names them. Svelte context usage isn't captured either.

• full type resolution: infers complex types without manual annotations, including generics, imported types, and inferred return types, with source locations for every declaration
• TSDoc/JSDoc parsing: extracts standard tags (@param, @returns, @example, @deprecated, etc.) plus @nodocs to exclude from docs, @internal kept as an internalMessage marker, and @mutates to flag side effects
• structured types: typeInfo trees beside the flat type strings, with union members, type arguments, tuple elements, and alias names recovered where TypeScript drops them (z.infer and friends); see the output format
• merged value+type symbols: a schema/type pair (const Foo = z.strictObject({...}) + type Foo = z.infer<typeof Foo>) documents the type with full structure, marked mergedValue since the name is also a runtime value
• Svelte 5 components: analyzes components via svelte2tsx, extracting prop types, defaults, bindability, snippet parameters, children detection, and exported template snippets, including JS components (props from the JSDoc @type on $props())
• Svelte 5 reactivity runes: detects $state, $state.raw, $derived, and $derived.by on variables and class fields via the reactivity field, in any analyzed file
• re-export tracking: alsoExportedFrom arrays with the forward view on ModuleJson.reExports, aliasOf for renames, default-slot entries named "default", export * from patterns, direct external re-exports, and resolveExportSurface to combine them all with ES star semantics
• dependency graphs: tracks imports between modules and computes dependents
• function overloads: captures all public overload signatures with per-overload JSDoc
• build-tool agnostic: files can come from disk, a build pipeline, or memory
• diagnostic collection: accumulates warnings and errors without halting, so you can report problems in batch

sveld is a Svelte component documentation generator that walks the AST and infers types from JSDoc annotations and literal values. svelte-docinfo instead uses the TypeScript compiler API (via svelte2tsx) as its source of truth, so it resolves imported types, generics, and complex inferred types without requiring @type annotations. It also analyzes TypeScript modules, not just .svelte files.

svelte-docinfo additionally tracks re-exports across modules, computes dependency graphs, and records source locations. It doesn't support Svelte 4 features like slots and dispatched events (Svelte 5 replaces them with snippets and callback props) or the context API.

See the output format reference for example JSON output.

Files are discovered from package.json exports, falling back to glob. -i supplies explicit patterns, --discovery glob skips exports, and --discovery exports fails when exports is missing or resolves to no files.

--source-dir sets the source directory (default src/lib, repeatable for monorepos). --source-root sets the base of output module paths (default: the single source dir, or the longest common prefix of several).

Compact JSON pairs well with jq:

JSON goes to stdout and messages go to stderr, so > and | capture clean JSON. -q silences info messages; warnings and errors still print.

--include patterns widen the source scope: each pattern's static base joins the source dirs, and module paths become relative to the widened root. A pattern with no base (**/*.ts, a root file) makes the whole project root source and logs an info line.

Regardless of --exclude, node_modules and dot-directories below a source dir are never source. The default excludes cover tests and the src/lib/internal/ convention (**/internal/**). Exports discovery also skips subpaths blocked by null exports entries ("./internal/*": null), using Node's best-match rules.

Absolute paths and patterns inside the project root are accepted; ones outside it are an error.

Exit codes: 0 success, 1 analysis errors, 2 CLI errors or a thrown analysis error (a missing or unloadable tsconfig.json, strict exports discovery failing).

• Arrows point from importer to imported: X depends on Y. Reads with gravity, so dependencies fall downward toward the foundation.
• Layers are assigned by longest-path-from-sink. A module's layer is one plus the deepest layer it transitively depends on. Sinks (no internal imports) land at the bottom.
• Hover a module to isolate its immediate neighbors. Edges split by direction: what the module depends on and what depends on it.

The bottom rows are the primitives that import nothing else in the library: path normalization, types, concurrency caps, the diagnostics schema. The middle rows are the per-kind TypeScript extractors and the file-system helpers. The top rows are the orchestrators: the persistent session on top of core analysis, then the one-shot wrappers and the vite plugin (both built directly on the session), then the cli.

Across 33 modules and 151 internal imports, the graph is naturally acyclic, so no back-edges had to be reversed to lay it out.

The layout is precomputed at build time by dependency_graph.gen.json.ts, which calls analyzeFromFiles on this project and runs a Sugiyama-style layered layout: longest-path-from-sink for layer assignment, dummy nodes on long edges, median-heuristic crossing reduction. The result is a small JSON sibling the Svelte component renders to SVG. No layout libraries — a few hundred lines, end to end.

Every surface returns the same envelope, AnalyzeResultJson: the programmatic entry points (analyze, analyzeFromFiles), the CLI's JSON, and the Vite plugin's virtual module.

diagnostics is covered in diagnostics. The CLI emits compact JSON, so an empty project prints {}; parse it through AnalyzeResultJson to restore the defaults.

A ModuleJson describes a single source file and its exports:

• path: file path relative to the source root (e.g., "math.ts")
• declarations: exported items from this module
• moduleComment: file-level JSDoc comment, if present
• dependencies: paths of modules this file imports
• dependents: paths of modules that import this file
• starExports: export * from './module' targets
• reExports: same-name re-export edges ({name, module, typeOnly, sourceLine}), the forward view of alsoExportedFrom (see Re-exports)
• externalReExports: direct re-exports from packages ({name, specifier, originalName?, typeOnly, sourceLine})
• externalStarExports: export * from 'pkg' specifiers as written
• partial: true when the module is a placeholder for a .svelte file that svelte2tsx failed to transform (see transform_failed)

Array fields are omitted from JSON when empty and default to [] after parsing.

Each declaration is a DeclarationJson, a discriminated union on kind with nine variants:

• "function": adds parameters, returnType, returnTypeInfo, returnDescription, overloads
• "variable": adds optional defaultValue (from @default) and reactivity (see Reactivity)
• "class": adds members, extends, implements, externalTypes
• "interface": adds members, extends, externalTypes, mergedValue
• "type": adds members, externalTypes, mergedValue
• "enum": adds members (enum values)
• "component": adds props, externalTypes, acceptsChildren, lang (Svelte components)
• "snippet": adds parameters (exported Svelte template snippets)
• "namespace": adds module, the path of the module projected by export * as ns from './x'

A name declared as both a value and a type, like the schema pattern export const Foo = z.strictObject({...}) + export type Foo = z.infer<typeof Foo>, produces one declaration. The type meaning documents like its un-merged equivalent (structure, members, typeInfo), and mergedValue: true marks that the name is also a runtime value, so generateImport emits import instead of import type. JSDoc falls back to the value declaration's comment when the type has none, and @nodocs on either declaration excludes the pair.

Shared fields on all variants:

• name, kind: identity. Default exports carry name === "default" (see Re-exports)
• docComment: JSDoc comment text
• typeSignature: the full type as a string, rendered by the TypeScript checker (see module paths below)
• typeInfo: a structured TypeJson tree beside the flat string, on variables and type aliases (plus members, component props, parameters, and return types via returnTypeInfo). See structured types below
• sourceLine: line number in the source file
• modifiers: e.g., "readonly", "static", "getter"
• genericParams: type parameters with constraints and defaults
• examples, deprecatedMessage, seeAlso, throws, since: from standard JSDoc tags
• internalMessage: from @internal, a marker rather than an exclusion (empty string for a bare tag)
• mutates: from @mutates, a Record<string, string> of target to description (empty for a target with no description). See tags
• alsoExportedFrom: modules that re-export this declaration
• aliasOf: the canonical {module, name} of a renamed re-export
• partial: true when extraction failed partway, so the data is incomplete

Declarations tagged @nodocs are excluded from the output and from the opt-in duplicate-name check.

Re-exports are encoded by shape:

• Same-name: the canonical declaration's alsoExportedFrom lists the modules that re-export it: one declaration, several import paths. The re-exporting module lists the same edges on ModuleJson.reExports, with module naming the canonical module (resolved through chains), so barrels are self-describing.
• Renamed: a declaration is synthesized in the re-exporting module with aliasOf: {module, name} pointing at the canonical. It inherits the canonical's analyzed shape (typeSignature, docComment, parameters, and so on); sourceLine is the local export specifier's line.
• Star exports: export * from './x' lands on ModuleJson.starExports, with no per-declaration entries.
• Gated canonicals: re-exporting a symbol from a module excluded from output (e.g. internal/) synthesizes a full alias even when the name is unchanged, since the canonical module emits nothing to link. Its aliasOf.module names a module absent from output, and no reExports edge is emitted.
• External re-exports: statements that directly name a package (export {x} from 'pkg', export * as ns from 'pkg', export * from 'pkg') land on externalReExports / externalStarExports with the specifier as written.

A re-export statement with its own JSDoc also synthesizes an alias in the re-exporting module, even when the name is unchanged, so the local content has somewhere to live. Local doc fields win; the canonical's fields fill gaps. @nodocs on a re-export suppresses both the link and the synthesis.

To get a module's complete export surface, call resolveExportSurface(modules, path). It combines declarations, re-export edges, externals, and star exports with ES semantics (explicit exports shadow star-projected names, names ambiguous between stars are excluded, default never projects), and reports star targets whose names it can't know.

Default-slot entries carry name === "default", the symbol's JS-spec name. Renames out of the default slot (export {default as Foo} from './x') carry name: "Foo" and aliasOf: {module, name: "default"}. Duplicate-name checks skip "default", since each module has its own default slot.

Namespace re-exports (export * as ns from './x') produce a "namespace" declaration whose module names the projected source. Namespaces don't inline members; render ns.a by reading that module's declarations.

Classes, interfaces, types, and enums list MemberJson entries in members, a discriminated union on kind with three variants:

• "function": methods and call signatures. Adds parameters, returnType, returnTypeInfo, returnDescription, overloads, and optional defaultValue (from @default, documenting the behavior when a callable option is omitted). A property typed by an external function (run?: typeof spawn) is a "variable" with the flat type text rather than the package's overloads and docs; a mixed callable keeps its local signatures
• "constructor": class constructors and construct signatures. Adds parameters, overloads
• "variable": properties, accessors, and index signatures. Adds optional defaultValue (from @default), typeInfo, and reactivity for class fields initialized with a Svelte rune

Nesting is exactly one level deep: members never contain members.

Member name is the source identifier, or a synthesized name where none exists: "constructor" (class constructor), "(construct)" and "(call)" (construct and call signatures on an interface or type alias), and index-signature names like "[key: string]" (the parameter name as written for interfaces; a synthesized key for type aliases).

Component declarations have a props array of ComponentPropJson entries, in source order, followed by any props an external type declares that the $props() destructuring names, in destructuring order:

• name, type: prop name and TypeScript type
• typeInfo: structured TypeJson tree, when it adds structure
• optional: whether the prop is optional
• description: from JSDoc on the prop
• defaultValue: default value as source text, if present
• bindable: set when the prop is declared with $bindable(), so <Foo bind:value /> works
• parameters: structured parameters for snippet-typed props (e.g., Snippet<[text: string]>)
• examples, deprecatedMessage, seeAlso, throws, since, internalMessage, mutates: from the prop's own doc comment. On a prop, mutates declares what the component writes into the object or array it's handed

ParameterJson deliberately lacks those tag fields: a prop is a named slot with its own documentation, while a parameter's @example, @deprecated, and similar tags belong on the enclosing function per the TSDoc spec. Parameters get their docs from @param only.

Functions, snippets, constructors, and snippet-typed props list ParameterJson entries in parameters:

• name: parameter name (e.g., "options"; a rest parameter's dots live in rest, not the name)
• type: resolved TypeScript type as a string
• typeInfo: structured TypeJson tree, when it adds structure
• optional: whether the parameter has a ? token
• rest: whether the parameter uses rest syntax (...args)
• description: from @param
• defaultValue: default value expression from the source, if present
• propertyDescriptions: sub-path to description, from dotted @param obj.prop tags on a named object parameter (destructured parameters aren't covered)

Functions and constructors with multiple signatures list OverloadJson entries in overloads. Each carries only the fields that vary per signature:

• typeSignature: the full overload signature as a string
• parameters: this overload's parameters, with its own @param descriptions
• returnType: return type for this overload (functions only)
• returnTypeInfo: structured TypeJson tree for the return type, when it adds structure
• genericParams: type parameters for this overload
• docComment: per-overload JSDoc text, if present
• returnDescription: from @returns on this overload

Symbol-scope tags (@example, @deprecated, and the rest) live on the parent declaration only, read from the primary overload. On a non-primary overload they emit misplaced_tag and are dropped. See Symbol-scope vs signature-scope.

reactivity appears on VariableDeclarationJson and VariableMemberJson when the initializer is a value-producing Svelte rune call: $state, $state.raw, $derived, or $derived.by. Detection is syntactic and runs on every file, so a plain .ts file is treated the same as .svelte.ts or a component script.

Only variables and class fields are annotated, not parameters or destructured bindings. $props and $bindable surface on ComponentPropJson instead.

Declarations and members with type parameters list GenericParamJson entries in genericParams:

• name: type parameter name (e.g., "T")
• constraint: extends constraint, if present
• defaultType: default type, if present

Flat type signatures are opaque strings. Where a typeInfo or returnTypeInfo tree exists, flatten it with typeJsonToTokens to render per node: link name tokens to declarations, syntax-highlight code tokens, and print text punctuation as-is.

The tokenizer decides spacing, separators, parentheses, and tuple labels; the renderer decides what each token looks like. typeJsonToText concatenates the same tokens into a plain string.

Output uses compact JSON via compactReplacer: empty arrays, false booleans, and undefined fields are stripped, so optional, acceptsChildren, partial, rest, bindable, and similar fields vanish at their default. The value key is exempt, so a {kind: "literal", value: false} type node survives. Parsing with the Zod schemas from types.ts (or AnalyzeResultJson for the full envelope) restores every default, so the round-trip is lossless.

Raw-JSON consumers (jq, pipelines that skip .parse()) must treat absent as false: decl.optional === false fails because the key is gone. Use the schemas, or truthiness checks like if (decl.optional).

These show the compact wire form, so empty and default fields are stripped.

A TypeScript function in math.ts:

A Svelte component Card.svelte with a snippet prop, children, and an exported snippet:

A rune module counter.svelte.ts exporting reactive state:

A barrel index.ts that re-exports clamp from math.ts under a new name and star-exports other.ts. The rename synthesizes a declaration with aliasOf that inherits the canonical's signature and docs, the star export lands on starExports, and the dependency fields connect the modules. A same-name re-export would instead add the barrel to the canonical's alsoExportedFrom.

See the types module for the full Zod schemas, and the API reference for all exported types.

Two tags vary per overload signature; the rest describe the symbol as a whole.

• Signature-scope: @param and @returns. These flow to the matching overload's parameters[i].description / returnDescription. Each overload can carry its own.
• Symbol-scope: @example, @deprecated, @internal, @since, @see, @throws, @mutates, @default, @nodocs. These describe the symbol as a whole and live on the parent declaration only.

A symbol-scope tag on a non-primary overload emits misplaced_tag and is dropped. Put these tags on the first overload signature: its JSDoc documents the symbol, while JSDoc on a later overload documents only that overload.

@param keys are matched against parameter names, and the leading - separator is stripped from the description. A dotted key (obj.prop) documents a property of a named object parameter.

Dotted keys land in ParameterJson's propertyDescriptions, keyed by sub-path (obj.prop → prop, obj.a.b → a.b). The property path isn't checked against the parameter's type. Destructured parameters (fn({a, b}: T), which TypeScript names __0) can't be matched by name, so they aren't covered.

A key whose name (or dotted root) matches no parameter drops its description and emits unknown_param with the key, usually a typo or a stale doc after a rename.

A non-standard tag for documenting mutations to parameters or external state: @mutates target - description. The target is everything before the first - (space-hyphen-space), so unlike @param it can be a hyphenated name or a phrase. Targets are not validated against the parameters, and backticks are stripped, so `options` and options are the same key:

• a parameter name: @mutates options - sets defaults in place
• a compound path: @mutates this.cache - inserts the result
• a multi-word external reference: @mutates `app_settings` row - bumps the revision
• a bare target with no description: @mutates `this`

The output is a Record<string, string> of target to description, empty for the bare form. Without a separator, the first line is the target and any following lines are the description.

On a component prop, @mutates declares that the component writes into the object or array it's handed, the same contract a function declares for a parameter: @mutates items - appends the selected entry. Reassigning a prop isn't a mutation in this sense; bindable covers that. The two combine: Svelte warns when a component mutates state the parent didn't bind, so an in-place write into a parent's $state usually sits on a $bindable prop.

@internal marks a symbol as not stable public API, per TSDoc. It lands as internalMessage on declarations and members of every kind, and on component props: an empty string for a bare tag, or the trailing prose (@internal used during development), kept separate from docComment.

It's a marker, not an exclusion: the declaration stays fully documented, so consumers can badge or filter it. To remove a declaration from output, use @nodocs; to omit whole modules, use exclude patterns.

@nodocs on a declaration removes it from the output entirely. It doesn't apply to members or component props, which stay in the output with no warning. It also affects:

• Duplicate checking (opt-in, via onDuplicates): a hidden helper named parse can coexist with a public parse in another module without duplicate_declaration.
• Re-exports: on a re-export statement, it drops the alsoExportedFrom link, any synthesized alias, and the module's reExports, starExports, or externalReExports / externalStarExports entry. The canonical declaration is unaffected.
• Merged value+type pairs: a const Foo + type Foo pair is one symbol, so the tag on either excludes it.

A comment tagged @module documents the file, not the next declaration. The text lands on ModuleJson.moduleComment and never in a declaration's docComment.

Svelte files have three module-comment sources, in priority order: a JSDoc @module in the instance <script>, one in <script module>, and the first HTML <!-- --> comment with @module at a line start. The highest-priority source wins, and more than one emits duplicate_comment (commentType: "module_comment"). Likewise, an HTML @component comment plus in-script component JSDoc emits it with commentType: "doc_comment", and the JSDoc wins.

A re-export with its own JSDoc synthesizes an alias in the re-exporting module, even when the name is unchanged. Its local doc fields win and the canonical's fill gaps. See Re-exports.

Three diagnostic kinds report tag problems, all warnings:

• misplaced_tag: a symbol-scope tag on a non-primary overload, or @nodocs in a @module comment
• unknown_param: @param key with no matching parameter
• duplicate_comment: more than one @module source in a Svelte file, or an HTML @component comment plus in-script component JSDoc

See diagnostics for details and tsdoc.ts for the parser.

Accumulated (non-fatal): appended to the diagnostics array while analysis continues. Covers type resolution failures, member or prop extraction failures, and JSDoc tag misuse. The result is still valid, and declarations or members with incomplete data are marked partial: true.

Thrown (fatal): setup-level problems throw from the public entry points:

• a missing or unloadable tsconfig.json: one that fails to parse, or an extends target that doesn't exist, like SvelteKit's generated tsconfig before svelte-kit sync has run
• Svelte older than 5
• invalid source options: empty sourcePaths, a path or absolute pattern outside projectRoot, or sourcePaths not under sourceRoot
• conflicting options: discovery: 'exports' with include, or resolveImport with resolveDependencies: false
• discovery: 'exports' when exports is missing or resolves to no files
• a name collision under onDuplicates: 'throw'

Wrap analyze / analyzeFromFiles, or createAnalysisSession and query, to handle these. svelte2tsx failures don't throw; they surface as transform_failed.

The table below marks each kind's lifecycle. Ingest-time kinds surface when files are ingested and persist with the file until it is re-ingested or deleted, discovery-time comes from file discovery, and unmarked kinds are recomputed on every analysis pass. See the session guide for how they combine.

diagnostics is a plain Array<Diagnostic> beside modules in AnalyzeResultJson. It round-trips through JSON.stringify and z.array(Diagnostic).parse. Each entry carries:

• kind: discriminant, one per failure mode (see table below)
• severity: "error" or "warning"
• file: POSIX-form and relative to the project root, with no leading ./; a file outside the project takes the ../ form. Join with projectRoot to get the absolute path. It names a file, not a module: ModuleJson.path is relative to sourceRoot, so don't look modules up by file.
• line, column: 1-based, optional. Absent when there's no precise position (e.g., a module-level skip). Positions in Svelte files point at the original .svelte source; one that can't be mapped is omitted
• message: human-readable description, with project-root paths made relative like file
• fields specific to the kind: symbolName, className, tagName, etc.

Severity is fixed per kind: every kind is a warning except transform_failed and module_unreadable, which are always error.

Use byKind to narrow to one variant with typed fields:

severity says how loud to be about a problem. partial: true says a declaration or member has incomplete data, from type_extraction_failed, signature_analysis_failed, or class_member_failed, and a ModuleJson is partial when it's a transform_failed placeholder. svelte_prop_failed sets no flag; the prop's type falls back to any. Check partial directly instead of matching diagnostics by file and line.

Read helpers for the diagnostics array:

• hasErrors, hasWarnings: boolean checks by severity
• errorsOf, warningsOf: filter by severity
• byKind: filter by kind, narrowed to the matching variant
• formatDiagnostic: format as './file.ts:10:5: error: message' (the './' prefix is fixed)

The CLI includes diagnostics in its JSON output, omitted when empty (parse through AnalyzeResultJson to restore []). Progress messages go to stderr; structured diagnostics appear only in the JSON:

Programmatically:

The Vite plugin's virtual module exports diagnostics too, so an app can render doc warnings without re-running analysis:

Absent optional fields (line, column) are omitted from JSON, per the compact output rules. The Vite plugin's modules and diagnostics exports are always present, even when empty. See diagnostics.ts for the Zod schemas and helpers.