SvelteUML

Static analysis tool that generates PlantUML architecture diagrams from SvelteKit codebases. Uses svelte2tsx + ts-morph to parse components, stores, routes, props, events, and server endpoints — producing class diagrams, package diagrams, or SVG/PNG output. No runtime required; analyzes source directly.

Quick Start

# Install globally
pnpm add -g svelteuml

# Or run without installing
pnpm dlx svelteuml generate ./my-sveltekit-app

# Generate a class diagram (default)
svelteuml generate ./my-sveltekit-app

# Generate to a specific file
svelteuml generate ./my-sveltekit-app -o docs/architecture.puml

# Generate SVG (requires Java + PlantUML)
svelteuml generate ./my-sveltekit-app -f svg -o diagram.svg

CLI Reference

Subcommands

Flags

Layout Directions

• top-to-bottom (default)
• left-to-right
• bottom-to-top
• right-to-left

Examples

# Generate with max depth 2
svelteuml generate ./my-app --max-depth 2

# Focus on a single component
svelteuml generate ./my-app --focus Button

# Package diagram
svelteuml generate ./my-app --package-diagram -o packages.puml

# Watch mode
svelteuml watch ./my-app

# Detect circular dependencies
svelteuml generate ./my-app --detect-circular

# Fail build on circular deps
svelteuml generate ./my-app --detect-circular --fail-on-circular

# Exclude test files and generated code
svelteuml generate ./my-app -e "**/*.test.ts" -e "**/__generated__/**"

# Exclude patterns from the output diagram
svelteuml generate ./my-app --exclude-patterns "**/node_modules/**"

# Left-to-right layout with no colors
svelteuml generate ./my-app --layout-direction left-to-right --disable-colors

# Pipe PlantUML text to external renderer
svelteuml generate ./my-app -f text | plantuml -pipe > diagram.svg

Features

Class Diagrams

Default diagram type. Shows classes, interfaces, stores, routes, components, and functions as PlantUML classes with stereotypes and members.

svelteuml generate ./my-app

Classes rendered with visibility (+, -, #), properties, methods, and type parameters. Stores show storeType and valueType. Routes show path segments, params, and groups.

Package Diagrams

Group symbols by their filesystem path into PlantUML package blocks. Shows high-level module structure without individual members.

svelteuml generate ./my-app --package-diagram

Component Edges

Detects Svelte component imports and draws --> arrows from parent to child component.

Store Subscription Edges

Detects $storeName auto-subscription in .svelte files (the Svelte $ prefix syntax). Draws ..> edges from component to store file labeled with the store name.

svelteuml generate ./my-app --hide-state-deps  # hide store edges

Server Load Edges

Tracks data flow from +page.server.ts / +layout.server.ts to the corresponding .svelte page. Detects $page.data and $page.url usage to draw ..> edges.

Slot Edges

Tracks <slot> and <slot name="..."> usage. Draws ..> edges labeled slot:<name> from child component back to parent.

Prop Flow Edges

Tracks prop passing from parent to child. Draws --> edges with prop type signatures.

ParentForm --> Button : onClick: (e: Event) => void

Event Edges

Tracks createEventDispatcher usage. Draws ..> edges from child to parent labeled with event names.

Circular Dependency Detection

Detect cycles in your dependency graph. Reports each cycle's file chain.

svelteuml generate ./my-app --detect-circular
# Circular dependency: src/lib/stores/auth.ts -> src/lib/utils/api.ts -> src/lib/stores/auth.ts

With --fail-on-circular, exits with code 1 (useful for CI gates).

Alias Grouping

Respects SvelteKit path aliases ($lib, $components, custom). Components under an alias are grouped into a PlantUML package with the alias name. Configurable via aliasOverrides.

Config File Support

Supports three config file formats (searched in order):

CLI flags override config file values.

Comments DSL (@uml.* tags)

Annotate Svelte components with HTML comments to control diagram behavior:

<!-- @uml.hide -->
<script>...</script>

Output Formats

# SVG output
svelteuml generate ./my-app -f svg -o diagram.svg

# PNG output
svelteuml generate ./my-app -f png -o diagram.png

# Text to stdout (pipe to other tools)
svelteuml generate ./my-app -f text > diagram.puml

Configuration Reference

Create .svelteumlrc.json in your project root:

{
  "targetDir": "./src",
  "outputPath": "docs/architecture.puml",
  "exclude": ["**/*.test.ts", "**/*.spec.ts"],
  "include": [],
  "maxDepth": 3,
  "excludeExternals": true,
  "aliasOverrides": {
    "$components": "./src/components",
    "$utils": "./src/lib/utils"
  }
}

Schema

CLI flags always override config file values.

Example Output

@startuml Diagram
skinparam classAttributeIconSize 0

package "routes" {
  package "(auth)" {
    class "+page" <<page>> {
      +load(): PageLoad
    }
    class "+layout" <<layout>> {
      +load(): LayoutLoad
    }
  }
  package "api/users" {
    class "+server" <<endpoint>> {
      +GET(): RequestHandler
      +POST(): RequestHandler
    }
  }
}

package "$lib" {
  class "stores/auth" <<store>> {
    storeType: writable
    valueType: User
  }
  class "components/Button" <<component>> {
    +label: string
    +disabled?: boolean
  }
}

"+page" ..> "stores/auth" : store
"+layout" ..> "stores/auth" : store
"+page" ..> "+layout" : session
@enduml

Architecture

SvelteUML uses a 5-phase pipeline:

┌─────────────┐    ┌───────────┐    ┌─────────────┐    ┌────────────┐    ┌───────────┐
│  Discovery  │───>│  Parsing  │───>│  Extraction │───>│ Resolution │───>│ Emission  │
│             │    │           │    │             │    │            │    │           │
│ Find files  │    │ svelte2tsx│    │  Symbols    │    │  Edges     │    │ PlantUML  │
│ Load config │    │ ts-morph  │    │  Props      │    │  Imports   │    │  DSL      │
│ Aliases     │    │ VFS       │    │  Routes     │    │  Reactive  │    │  SVG/PNG  │
└─────────────┘    └───────────┘    └─────────────┘    └────────────┘    └───────────┘

1. Discovery — Recursively find .svelte, .ts, .js files. Load svelte.config.js and .svelte-kit/tsconfig.json for path aliases.
2. Parsing — Transform .svelte SFCs to TSX via svelte2tsx. Build a ts-morph Project with virtual file system.
3. Extraction — Extract components, props, stores, routes, server endpoints, lib functions, classes, events.
4. Resolution — Scan imports, build dependency edges (composition, inheritance, type, store, server-load, prop-flow, slot, event). Track reactive $state/$derived cross-file references.
5. Emission — Generate PlantUML DSL with nested packages, stereotypes, relationship arrows. Optionally render to SVG/PNG.

Development

Property-Based Testing

Uses fast-check alongside unit tests.

Contributing

1. Clone: git clone https://github.com/Jonathangadeaharder/svelteuml.git
2. Install: pnpm install
3. Branch: git checkout -b feature/my-feature
4. Check: pnpm test && pnpm run typecheck && pnpm run lint
5. PR: Submit a pull request

License

MIT