Efficient Svelte Storybook Mock

Configure comprehensive module mocks for SvelteKit applications in Storybook, enabling isolated component development with mocked routing, stores, and platform APIs.

When to Use This Command

Run this command when...

• Your Svelte components import SvelteKit modules like $app/navigation, $app/stores, or $app/environment that fail in the Storybook context
• You need to mock API calls, server-side load functions, or environment variables for isolated story rendering
• Your stories require specific application state like authenticated user sessions, navigation context, or feature flags

Do NOT use this command when...

• Your components have no SvelteKit-specific imports and render purely from props
• You need to test actual navigation or server-side behavior -- use Playwright E2E tests instead

Quick Start

Copy
# .claude/commands/efficient-svelte-storybook-mock.md
# Setup Storybook mocks for SvelteKit
Mock: $ARGUMENTS

Copy
# Run the command
claude "efficient-svelte-storybook-mock setup mocks for $app/navigation goto and $app/stores page store"

Expected output:
- Mock configuration in .storybook/preview.ts
- $app/navigation mock with goto, invalidate, afterNavigate
- $app/stores mock with page, navigating, updated stores
- Per-story override patterns for different states
- Verification test for mock behavior

Core Concepts

Concept	Description
Module Mocking	Replacing SvelteKit runtime modules with controllable test doubles
Store Mocks	Writable store substitutes for $app/stores (page, navigating, updated)
Navigation Mocks	Stub implementations for goto, invalidate, and navigation lifecycle
Environment Mocks	Controlled $app/environment values (browser, dev, version)
Story Overrides	Per-story mock customization for different application states

Mock Architecture:

  Svelte Component
  |         |         |
 $app/    $app/     $app/
 stores   navigation environment
  |         |         |
  [Storybook Mock Layer]
  |         |         |
 Writable  Stub Fn   Static
 Stores    (goto)    Values
  |         |         |
  [Story-Level Overrides]
       |
  Isolated Rendering

Configuration

Parameter	Default	Description
Framework	@storybook/sveltekit	Required framework package for mock support
Mock Scope	Global + per-story	Whether mocks apply globally or per-story
Store Initial State	Empty/default	Default values for mocked SvelteKit stores
Navigation Behavior	No-op	Whether goto logs, throws, or silently succeeds
Environment Mode	Browser=true, dev=false	Default $app/environment mock values

Best Practices

1. Use @storybook/sveltekit -- this package provides built-in mock support for SvelteKit modules. Avoid hand-rolling mocks when framework support exists
2. Set sensible global defaults -- configure page store with a realistic URL and params globally, then override per-story only when needed
3. Mock at the narrowest scope -- global mocks affect all stories. Use story-level overrides for specific states like "user is logged out" or "page is /admin"
4. Log navigation calls -- configure goto mocks to log calls using Storybook actions so you can verify navigation behavior in the Actions panel
5. Keep mocks simple -- mocks should return predictable, minimal data. Complex mock logic indicates the component may need refactoring to reduce coupling

Common Issues

1. $app/stores is undefined -- ensure you are using @storybook/sveltekit as your framework, not @storybook/svelte-vite. The latter does not provide automatic module mocking
2. Mock state persists between stories -- writable stores in mocks may retain state across stories. Reset store values in story decorators or use a beforeEach cleanup
3. Server-only imports crash Storybook -- modules importing from $app/server or using top-level await need conditional imports or must be split into client-safe modules