introduction #

svelte-docinfo extracts JSON describing the exports of TypeScript and Svelte modules for open-ended use cases like docs, code search, and dev tools. It uses the TypeScript compiler API and svelte2tsx to resolve types, track exports+imports, and extract semantic details. The npm package has a Vite plugin, CLI, and programmatic API.

svelte-docinfo is largely inspired by sveld, but uses the TypeScript compiler API instead of AST-only inspection, and also analyzes TypeScript modules. See the comparison below.

The library is mostly complete for Svelte 5 and used in production websites, but you may find gaps and flaws -- please open issues for bugs, and discussions for everything else!

Dependencies are minimal and the tool's scope is limited to data, not presentation. These docs were made using the data produced by svelte-docinfo, like the architecture and API reference, with fuz_ui components.

AI disclosure: the code and docs beyond the intro were mostly written by Claude Code with uneven human guidance. The first release took 5 months of intermittent work and ~500 manual commits to extract its initial implementation from fuz_ui, which was more limited, lacking the fancy TS compiler usage, and grew slowly over years without AI assistance.

Install
#

Published as svelte-docinfo to npm:

npm i -D svelte-docinfo

Usage
#

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:

import {modules} from 'virtual:svelte-docinfo';

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

# Analyze the current project and print JSON to stdout npx svelte-docinfo # Analyze a specific directory and write to a file npx svelte-docinfo ./packages/my-lib -o docs/library.json

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

import {analyzeFromFiles} from 'svelte-docinfo'; const {modules, diagnostics} = await analyzeFromFiles({ projectRoot: process.cwd(), });

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

import {analyze, createSourceOptions} from 'svelte-docinfo'; const {modules} = await analyze({ // files outside sourcePaths (default src/lib) feed the checker but emit no module sourceFiles: [{id: '/project/src/lib/file.ts', content: '...'}], sourceOptions: createSourceOptions('/project'), });

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.

Not supported
#

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.

Key features
#

  • 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

Compared to sveld
#

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.

Example output
#

See the output format reference for example JSON output.