@motiadev/stream-client-svelte

Motia Stream Client Svelte Package – Responsible for managing streams of data in Svelte 5 applications.

For more information about Motia Streams, please refer to the Motia Streams documentation.

Overview

@motiadev/stream-client-svelte provides a set of Svelte 5 utilities and functions for integrating Motia's real-time streaming capabilities into your Svelte applications. It enables you to subscribe to individual stream items, groups, and handle real-time events with idiomatic Svelte 5 patterns using runes.

Installation

npm install @motiadev/stream-client-svelte

Requirements

• Svelte 5.0.0 or higher
• TypeScript support recommended

Development & Examples

This package is built as a SvelteKit library with a built-in development server that includes interactive examples and documentation.

Running the Examples

# Clone the repository and navigate to the package
cd packages/stream-client-svelte

# Install dependencies
pnpm install

# Start the development server
pnpm dev

The development server will start at http://localhost:5173 and includes:

• Interactive Examples: Live demonstrations of all library features
• User Profile Example: Single item subscription with real-time updates
• Users List Example: Group subscriptions with filtering and sorting
• Chat Room Example: Advanced bidirectional communication with typing indicators
• Full Documentation: Complete API reference and usage guides

Building the Library

# Build the library for distribution
pnpm build

# Package the library (generates dist/ folder)
pnpm package

Exports

• Stream, StreamItemSubscription, StreamGroupSubscription
  (Re-exported from @motiadev/stream-client-browser)
• MotiaStreamProvider
  Svelte component for initializing and supplying the stream context.
• useMotiaStream
  Function to access the current stream instance from context.
• useStreamItem
  Function to subscribe to a single stream item using Svelte 5 runes.
• useStreamGroup
  Function to subscribe to a group of stream items using Svelte 5 runes.
• useStreamEventHandler
  Function to attach event listeners to stream subscriptions.

Usage

1. MotiaStreamProvider

Wrap your application (or a subtree) with MotiaStreamProvider to initialize the stream and provide it via context.

<script>
  import { MotiaStreamProvider } from '@motiadev/stream-client-svelte'
  import App from './App.svelte'
</script>

<MotiaStreamProvider address="wss://your-stream-server">
  <App />
</MotiaStreamProvider>

Props:

• address (string): The WebSocket address of your Motia stream server.

2. useMotiaStream

Access the current stream instance anywhere within the provider.

<script>
  import { useMotiaStream } from '@motiadev/stream-client-svelte'

  const { stream } = useMotiaStream()
</script>

3. useStreamItem

Subscribe to a single item in a stream and receive real-time updates using Svelte 5 runes.

<script>
  import { useStreamItem } from '@motiadev/stream-client-svelte'

  const { data, event } = useStreamItem({
    /**
     * The stream name from motia Server
     */
    streamName: 'users',
    /**
     * The group id containing the item
     */
    groupId: 'group-123',
    /**
     * The id of the item to subscribe to
     */
    id: 'user-123',
  })
</script>

{#if data}
  <div>{data.name}</div>
{:else}
  <div>Loading...</div>
{/if}

• data: The current value of the item (typed and reactive).
• event: The subscription object to subscribe to custom events. Check useStreamEventHandler for more information.

4. useStreamGroup

Subscribe to a group of items in a stream using Svelte 5 runes.

<script>
  import { useStreamGroup } from '@motiadev/stream-client-svelte'

  const { data, event } = useStreamGroup({
    /**
     * The stream name from motia Server
     */
    streamName: 'users',
    /**
     * The group id to subscribe to
     */
    groupId: 'admins',
  })
</script>

{#each data as user (user.id)}
  <div>{user.name}</div>
{/each}

• data: Array of current group items (reactive).
• event: The group subscription object.

5. useStreamEventHandler

Attach custom event listeners to a stream subscription.

<script>
  import { useStreamItem, useStreamEventHandler } from '@motiadev/stream-client-svelte'

  const { data, event } = useStreamItem({
    streamName: 'users',
    groupId: 'group-123',
    id: 'user-123'
  })

  const handleCustomEvent = (eventData) => {
    // handle event
    console.log('Custom event received:', eventData)
  }

  useStreamEventHandler({
    event,
    type: 'custom-event',
    listener: handleCustomEvent
  })
</script>

API Reference

MotiaStreamProvider

• Props:
  • address: string – WebSocket address for the stream server.
  • children: Snippet – Child components

useMotiaStream

• Returns { stream } from context.

useStreamItem

• Args: { streamName: string, groupId: string, id: string }
• Returns: { data: TData | null, event: StreamSubscription | null }

useStreamGroup

• Args: { streamName: string, groupId: string, sortKey?: keyof TData }
• Returns: { data: TData[], event: StreamSubscription | null }

useStreamEventHandler

• Args: { event: StreamSubscription | null, type: string, listener: (event: any) => void }

Example

<!-- App.svelte -->
<script>
  import { MotiaStreamProvider } from '@motiadev/stream-client-svelte'
  import UserComponent from './UserComponent.svelte'
</script>

<MotiaStreamProvider address="wss://your-stream-server">
  <UserComponent userId="user-123" />
</MotiaStreamProvider>

<!-- UserComponent.svelte -->
<script>
  import { useStreamItem, useStreamEventHandler } from '@motiadev/stream-client-svelte'

  let { userId } = $props()

  const { data, event } = useStreamItem({
    streamName: 'users',
    groupId: 'all-users',
    id: userId,
  })

  const handleUserUpdate = (e) => {
    alert('User updated!')
  }

  useStreamEventHandler({
    event,
    type: 'user-updated',
    listener: handleUserUpdate
  })
</script>

{#if data}
  <div>{data.name}</div>
{:else}
  <div>Loading...</div>
{/if}

Notes

• All functions must be used within a MotiaStreamProvider.
• The library is designed to work seamlessly with Svelte 5 runes for reactive state management.
• The library is designed to work seamlessly with Motia's event-driven architecture.
• For advanced stream management, refer to the @motiadev/stream-client-browser documentation.

License

MIT