Skip to content
XMachines

@xmachines/play-svelte

API / @xmachines/play-svelte

Svelte 5 renderer for the XMachines Play architecture. It connects an actor to a catalog-driven @xmachines/json-render-svelte UI, with Svelte 5 runes and atoms.

License: MIT Version

Installation

Terminal window
pnpm add @xmachines/play-svelte

Peer dependencies. Install them separately:

Terminal window
pnpm add svelte@^5.0.0 @xmachines/play @xmachines/play-atom @xstate/store@^4.2.3 \
  @xmachines/json-render-core@^0.20.0-xm.4 @xmachines/json-render-svelte@^0.20.0-xm.4 @xmachines/json-render-xstate@^0.20.0-xm.4

@xstate/store is the peer of @xmachines/play-atom, and not of this package: this package reads the atom through @xmachines/play-atom and imports the engine in no source file. Install ONE copy of it.

Usage

Basic setup

Define the catalog and the registry one time. Then give both to PlayUIProvider, together with your actor. PlayRenderer then renders the current view of the actor:

App.svelte
<script lang="ts">
  import { defineRegistry, PlayUIProvider, PlayRenderer } from "@xmachines/play-svelte";
  import { authCatalog } from "./catalog.js";
  import Login from "./components/Login.svelte";
  import Dashboard from "./components/Dashboard.svelte";


  let { actor } = $props();


  const registryResult = defineRegistry(authCatalog, {
    components: { Login, Dashboard },
    actions: {
      login: async (params) => {
        actor.send({ type: "auth.login", username: params?.username });
      },
      logout: async () => actor.send({ type: "auth.logout" }),
    },
  });
</script>


<PlayUIProvider {actor} {registryResult}>
  <PlayRenderer />
</PlayUIProvider>

Lower-level: ActorProvider

Use ActorProvider directly when you need more control over the rendering. For example, use it to add a custom layout, or to add each @xmachines/json-render-svelte provider one by one:

<script lang="ts">
  import { ActorProvider } from "@xmachines/play-svelte";


  let { actor, registryResult, children } = $props();


  function handleError(error: unknown, reset: () => void) {
    console.error(error);
  }
</script>


{#snippet loadingSnippet()}
  <div>Loading…</div>
{/snippet}


<ActorProvider {actor} {registryResult} fallback={loadingSnippet} onError={handleError}>
  <!-- children rendered inside StateProvider tree -->
  {@render children()}
</ActorProvider>

Accessing the actor from child components

import { getActorContext } from "@xmachines/play-svelte";


// Inside a Svelte component that is a descendant of ActorProvider:
const actor = getActorContext();
actor.send({ type: "some.event" });

API Summary

Components

ComponentDescription
<PlayUIProvider>Composite provider. It wraps ActorProvider and JsonUIProvider. Use it as the standard entry point for an actor-driven UI.
<ActorProvider>Primitive provider — owns actor lifecycle, atom subscription, per-view StateStore, and onRenderError injection.
<PlayRenderer>Zero-prop leaf component — reads getPlayViewContext() and renders <Renderer> from @xmachines/json-render-svelte.

Functions

FunctionDescription
defineRegistry(catalog, options)Creates a typed component registry. Wraps @xmachines/json-render-svelte’s defineRegistry with catalog-typed params on action handlers. Import from @xmachines/play-svelte, not @xmachines/json-render-svelte.
getActorContext()Returns the AnyPlayActor of the nearest ActorProvider ancestor. It throws when the caller is outside the provider tree.
getPlayViewContext()Returns the ViewContextValue (spec, registry, handlers, store) from the nearest ActorProvider ancestor. Every field is a GETTER: read view.spec where you use it, and destructure it not.
setActorContext(actor)Sets the actor context. ActorProvider uses it internally.

The names of this package are Svelte names. @xmachines/play-react, @xmachines/play-vue and @xmachines/play-solid export useActor and usePlayView, because use* is the convention of a React hook and of a Vue composable. Svelte has getContext and setContext, and @xmachines/json-render-svelte names its own readers get*Context. This package re-exports that library, so one import surface holds one convention. The difference is deliberate, and it is no drift.

Types

TypeDescription
ActorProviderPropsProps for <ActorProvider>: actor, registryResult, optional store, fallback snippet, onError, onRenderError, children.
PlayUIProviderPropsExtends ActorProviderProps with optional validationFunctions, navigate, and functions.
ViewContextValueThe view context shape that ActorProvider provides and PlayRenderer reads.
AnyPlayActorViewActor — the actor shape that ActorProvider and getActorContext accept.
DefineRegistryOptions<C>Options for defineRegistry: components, catalog-typed actions, and onRenderError.
ActionFn<C, K>The handler type for one action. The params come from the catalog.
Actions<C>Map of catalog-typed action handlers.
SetStateThe state setter type. Each action handler receives it as the second argument.
RenderErrorHandlerThe callback (error: unknown, elementType: string) => void. The renderer calls it when a catalog component throws.

Re-exports from @xmachines/json-render-svelte

Import everything from @xmachines/play-svelte. This package re-exports these providers:

import {
  JsonUIProvider,
  StateProvider,
  ActionProvider,
  VisibilityProvider,
  ValidationProvider,
  Renderer,
  getBoundProp,
  getStateValue,
} from "@xmachines/play-svelte";


// Types
import type {
  JSONUIProviderProps,
  BaseComponentProps,
  ComponentFn,
  ComponentContext,
} from "@xmachines/play-svelte";

License

MIT — see LICENSE.

@xmachines/play-svelte - Svelte renderer for the XMachines Play architecture

The package splits the provider from the renderer, in the same way as @xmachines/json-render-svelte:

  • ActorProvider: the low-level provider. It owns the actor lifecycle, the atom subscription, the StateStore of each view, and the injection of onRenderError
  • PlayUIProvider: the composite provider (ActorProvider and JsonUIProvider)
  • PlayRenderer: the leaf without props. It reads getPlayViewContext() and renders the Renderer

The package re-exports the primitives of @xmachines/json-render-svelte. A consumer therefore imports everything from @xmachines/play-svelte, and not from @xmachines/json-render-svelte.

Interfaces

Type Aliases

Variables

Functions

References

ActionProvider

Renames and re-exports PlayRenderer

ActorProvider

Renames and re-exports PlayRenderer

FieldValidationState

Renames and re-exports JSONUIProviderProps

getBoundProp

Renames and re-exports JSONUIProviderProps

getFieldValidation

Renames and re-exports JSONUIProviderProps

getStateValue

Renames and re-exports JSONUIProviderProps

getValidationContext

Renames and re-exports JSONUIProviderProps

JsonUIProvider

Renames and re-exports PlayRenderer

PlayUIProvider

Renames and re-exports PlayRenderer

Renderer

Renames and re-exports PlayRenderer

StateProvider

Renames and re-exports PlayRenderer

ValidationProvider

Renames and re-exports PlayRenderer

VisibilityProvider

Renames and re-exports PlayRenderer