@composable-svelte/core

A Composable Architecture for Svelte 5 - Type-safe state management with reducers, effects, and navigation

Inspired by The Composable Architecture (TCA) from Swift/iOS, adapted for Svelte 5 and TypeScript.

Features

• ✅ Pure Reducers: Predictable state management with (state, action, deps) => [newState, effect]
• ✅ Declarative Effects: Side effects as data structures (run, fireAndForget, batch, merge, cancel)
• ✅ Composability: Nest and scope reducers like Lego blocks
• ✅ Collection Management: forEach combinator for managing dynamic arrays of child features (92% less boilerplate)
• ✅ Type-Safe Navigation: State-driven navigation with Modal, Sheet, Drawer, Alert, NavigationStack
• ✅ Internationalization: Complete i18n with ICU MessageFormat, locale detection, framework formatters
• ✅ Server-Side Rendering: Production-ready SSR with Fastify, state hydration, security hardening
• ✅ Static Site Generation: Multi-locale SSG with dynamic routes and build-time optimization
• ✅ Svelte 5 Runes: Full integration with Svelte's reactivity system (`$state`, `$derived`)
• ✅ TestStore: Exhaustive action testing with send/receive pattern
• ✅ Complete Backend: API client, WebSocket, Storage, Clock dependencies
• ✅ 73+ Components: shadcn-svelte integration with reducer-driven patterns
• ✅ URL Routing: Browser history sync with pattern matching
• ✅ 500+ Tests: Comprehensive test coverage across all modules

Installation

```bash npm install @composable-svelte/core

or

pnpm add @composable-svelte/core

or

yarn add @composable-svelte/core ```

Peer Dependencies: Svelte 5.0.0 or higher

Quick Start

1. Define Your State and Actions

```typescript import { createStore, Effect } from '@composable-svelte/core';

interface CounterState { count: number; isLoading: boolean; }

type CounterAction = | { type: 'increment' } | { type: 'decrement' } | { type: 'incrementAsync' } | { type: 'incrementCompleted' }; ```

2. Create a Reducer

```typescript const counterReducer = ( state: CounterState, action: CounterAction, deps: {} ): [CounterState, Effect] => { switch (action.type) { case 'increment': return [{ ...state, count: state.count + 1 }, Effect.none()];

case 'decrement':
  return [{ ...state, count: state.count - 1 }, Effect.none()];

case 'incrementAsync':
  return [
    { ...state, isLoading: true },
    Effect.run(async (dispatch) => {
      await new Promise(resolve => setTimeout(resolve, 1000));
      dispatch({ type: 'incrementCompleted' });
    })
  ];

case 'incrementCompleted':
  return [
    { ...state, count: state.count + 1, isLoading: false },
    Effect.none()
  ];

} }; ```

3. Create the Store

```typescript const store = createStore({ initialState: { count: 0, isLoading: false }, reducer: counterReducer, dependencies: {} }); ```

4. Use in Svelte Component

```svelte

Documentation

Comprehensive documentation is available in the `docs/` directory:

• Getting Started - First app tutorial
• Core Concepts - Store, reducers, effects, composition, testing
• Navigation - Tree-based navigation, components, dismiss patterns
• DSL - Destinations, matchers, scope helpers
• Animation - Motion One integration
• Backend - API client, WebSocket, dependencies
• Routing - URL synchronization
• API Reference - Complete API documentation
• Troubleshooting - Common issues and solutions
• Migration - From Redux, TCA, MobX, Svelte stores

Examples

See the `examples/` directory for working examples:

• Styleguide - Component showcase with 73+ components
• Product Gallery - Full-featured product browsing app
• URL Routing - Browser history integration examples

Contributing

Contributions are welcome! This project follows a specification-first approach. See CLAUDE.md for contributor guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

Heavily inspired by The Composable Architecture by Point-Free. Adapted for Svelte 5 and TypeScript with love.

Links

• Documentation
• GitHub Repository
• Issue Tracker
• Changelog