createSynapseCtx

TL;DR. createSynapseCtx(module, options?) wraps a Synapse module in a React Context + HOC: child components take storage/selectors/actions/state$ through hooks, without threading a prop by hand. You pass the handle itself (not a call) — since v6 the C-form is synchronous, so the store is ready for the first frame (SSR by construction), and loadingComponent is only a fallback render for an async store that couldn't be built synchronously.

Same domain — the pokemonSynapse assembled on the previous pages. This is the "provider" way to hand it to the tree; the alternative (manual await + prop) is awaitSynapse, which is what the demo in the module actually uses.

When to use it

When you don't need it

Creating the context

import { createSynapseCtx, useSelector } from 'synapse-storage/react'
import { pokemonSynapse } from './pokemon.synapse'   // the lazy handle from previous pages

// Pass the handle ITSELF, not a call. The factory starts lazily on the first mount, not on import.
const {
  contextSynapse,       // HOC — wraps a component, providing the context
  useSynapseStorage,    // () => IStorage<PokemonState>
  useSynapseSelectors,  // () => PokemonSelectors
  useSynapseActions,    // () => PokemonDispatcher (actions)
  useSynapseState$,     // () => Observable<PokemonState> (only with effects)
  cleanupSynapse,       // () => Promise<void>
} = createSynapseCtx(pokemonSynapse, {
  loadingComponent: <div>Loading the pokedex...</div>,  // FALLBACK render: only if the store couldn't be
                                                        // built synchronously (normally the C-form is ready at once)
})

options — the only optional argument:

Using the hooks in child components

// Child components are called ONLY inside the contextSynapse HOC

function PokemonGrid() {
  const selectors = useSynapseSelectors()
  const actions = useSynapseActions()

  const filteredList = useSelector(selectors.filteredList)   // reactive values
  const isListLoading = useSelector(selectors.isListLoading)

  return (
    <div>
      {filteredList?.map((p) => (
        <button key={p.id} onClick={() => actions.selectPokemon(p.id)}>{p.name}</button>
      ))}
      {isListLoading && <span>Loading...</span>}
    </div>
  )
}

function SearchInput() {
  const selectors = useSynapseSelectors()
  const actions = useSynapseActions()
  const query = useSelector(selectors.searchQuery)

  return <input value={query ?? ''} onChange={(e) => actions.setSearchQuery(e.target.value)} />
}

function DirectAccess() {
  const storage = useSynapseStorage()
  // Direct access to the storage — e.g. getStateSync(), update(), set()
  const state = storage.getStateSync()
}

HOC contextSynapse()

function Pokedex() {
  const actions = useSynapseActions()
  return (
    <div>
      <button onClick={() => actions.loadList()}>Reload</button>
      <SearchInput />
      <PokemonGrid />
    </div>
  )
}

// Wrap it. Normally the store is synchronously ready for the first frame; loadingComponent is just a fallback render.
const PokedexWithContext = contextSynapse(Pokedex)

// Usage in JSX:
<PokedexWithContext />

useSynapseState$ (only with effects)

// Available only if effects were passed to the factory (pokemon — yes).
// Returns Observable<PokemonState> for use with RxJS.

const { useSynapseState$ } = createSynapseCtx(pokemonSynapse)

function StateLogger() {
  const state$ = useSynapseState$()

  useEffect(() => {
    const sub = state$.subscribe((state) => console.log('selected:', state.selectedPokemonId))
    return () => sub.unsubscribe()
  }, [state$])
}

Reactive reads in a component

Writes still go through actions, but reading can be reactive — straight from the selector's stream (.$):

import { useObservable, useSubscription } from 'synapse-storage/react'

function DebouncedSearch() {
  const selectors = useSynapseSelectors()

  const debounced = useObservable(
    () => selectors.searchQuery.$.pipe(debounceTime(300), distinctUntilChanged()),
    '',
    [selectors],
  )

  useSubscription(() => selectors.favoriteCount.$.pipe(skip(1), tap(logFavChange)).subscribe(), [selectors])

  return <div>{debounced}</div>
}

Cleanup

// Manual cleanup of the context and resources
await cleanupSynapse()

// For a class-handle it delegates to handle.destroy() (LIFO teardown + memoization reset) —
// the next mount will run the factory again.

Three variants of createSynapseCtx

// 1. Basic (storage + selectors)
// Available: useSynapseStorage, useSynapseSelectors, cleanupSynapse
const ctx = createSynapseCtx(basicSynapse)

// 2. With a dispatcher (+ actions)
// Available: + useSynapseActions
const ctx = createSynapseCtx(dispatcherSynapse)

// 3. With effects (+ state$) — the pokemon case
// Available: + useSynapseState$
const ctx = createSynapseCtx(pokemonSynapse)

SSR — server-rendering seeded sync stores

Since 6.0.0 SSR is enabled by construction — there is no separate ssr flag anymore (removed). The C-form construction is synchronous, so on the server the Provider builds a fresh shell per render (buildSyncShell) and synchronously seeds its dehydratedState. Classic renderToString only (streaming/Suspense is out of scope).

The full runnable cycle (dehydrate → renderToString → hydration) is in SynapseCtxSsrExample.tsx (on the Posts domain; below the same mechanics are shown on pokemon).

Previously createSynapseCtx gated children behind loadingComponent until the module was ready, and server rendering was enabled by the ssr: true flag. Now the store is always synchronously ready for the first frame, so server-rendering seeded content is the default behavior, and loadingComponent remains only a fallback render (an async store that couldn't be built synchronously).

Options

const PokemonCtx = createSynapseCtx(pokemonSynapse, {
  loadingComponent: <Spinner />, // fallback render (normally the C-form is ready for the first frame)
})

The dehydrate helper and the Provider prop:

// Server helper: collect a serializable store snapshot.
dehydrate(opts?: { initialState?: Partial<TState> }): Promise<TState>

// Provider (any HOC from contextSynapse) accepts the snapshot as a prop:
<Wrapped dehydratedState={snapshot} />

Server: build the snapshot

dehydrate creates a per-request fork of the module (parallel requests do not share state — no request bleed), seeds initialState via hydrate, and returns a serializable snapshot. On the server the Provider then builds a fresh shell per render and synchronously seeds it with this snapshot, so renderToString returns ready content on the first render (the main singleton is left untouched — request isolation by construction).

// Any data-fetching path (the pokemon ApiClient, etc.) → a snapshot.
const list = await fetchInitialPokemon()
const dehydrated = await PokemonCtx.dehydrate({ initialState: { pokemonList: list } })

const html = renderToString(<PokedexWithContext dehydratedState={dehydrated} />)
// serialize into HTML: window.__SYNAPSE_STATE__ = JSON.stringify(dehydrated)

RSC / 'use client' boundary. createSynapseCtx is usually called from a 'use client' module, so its dehydrate (a closure) cannot be imported on the server (RSC / 'server only'). For that case there is a server-safe dehydrateModule from synapse-storage/utils — no React dependencies, takes the module explicitly. dehydrate wraps it (same logic, no duplication):

typescript

копировать

import { dehydrateModule } from 'synapse-storage/utils'

// in a server (RSC) file — pokemonSynapse is imported directly, no 'use client' context
const dehydrated = await dehydrateModule(pokemonSynapse, { state: { pokemonList: list } })

state is merged on top of the fork's initialState (shallow, top-level) — you may pass only the changed fields; nested objects are replaced wholesale.

Client: hydrate with the same snapshot

The snapshot arrives as a prop and is seeded into the store synchronously before the first render → the client HTML matches the server → no hydration mismatch. Init/mutations/lazy-load continue on the client afterwards.

const dehydrated = JSON.parse(window.__SYNAPSE_STATE__)

hydrateRoot(container, <PokedexWithContext dehydratedState={dehydrated} />)

Guarantees and limitations

SSR — data-less "background" providers

Since 6.0.0 the SSR shell is derived by the C-form itself — the manual ssrShell, the object form with wire, and the functional factory have been removed. The only form is the synchronous config (see createSynapse).

The section above server-renders a store that received server data (dehydratedState). But some providers wrap a large subtree (the app shell) yet have no server data of their own — presence, relations, a media-player. Previously their store was built by an async factory and wasn't synchronously ready on the server, so the provider hit the loadingComponent gate and rendered nothing — cutting off the entire subtree below it, including a correctly seeded feed two levels deeper.

Now construction is synchronous by construction: storage/dispatcher/selectors are built from initialState in a single tick, while everything async (deps, endpoints, WS) lives in the effects factory, which does not run on the server. So every C-form module with a synchronous storage has buildSyncShell() — a way to synchronously bring up an "empty" store from initialState so the provider renders children on the server. The full store (with dependencies and effects) is assembled on the client afterwards, after which the context switches to it seamlessly.

Nothing special to declare

The shell is derived from the sync core — just write a plain C-form and keep everything async in effects:

import { createSynapse } from 'synapse-storage/utils'
import { MemoryStorage } from 'synapse-storage/core'

export const presenceSynapse = createSynapse({
  // sync core — the library builds the SSR shell from it automatically
  storage: () => new MemoryStorage<PresenceState>({ name: 'presence', initialState }),
  dispatcher: (s) => new PresenceDispatcher(s),
  selectors: (s) => new PresenceSelectors(s),
  dependencies: [coreSynapse],                       // gate for the START of effects (not construction)
  // async — client only (endpoints / WS); does not run on the server
  effects: async () => new PresenceEffects(await getPresenceEndpoints(), coreSynapse.state$),
})

Server-safe storage. If the storage is client-only (LocalStorage needs localStorage, a media-player reads tabId/broadcast) — wrap the factory in browserStorage(config, { client }) (exported from synapse-storage/core): MemoryStorage on the server, client(config) in the browser. Both branches are a sync store of the same shape, and the type is inferred without manual generics. See SSR hydration.

The provider

Nothing to turn on — the call site is a plain createSynapseCtx. A background provider simply passes its children through:

export const { contextSynapse: withPresence } =
  createSynapseCtx(presenceSynapse, { loadingComponent: null })

export const PresenceProvider = withPresence(({ children }) => <>{children}</>)

On the server PresenceProvider renders its children (the whole subtree reaches the HTML); on the client the first frame renders the same empty shell (matching the server — no hydration mismatch), then upgrades to the real store.

How it works

Gotchas

dehydrate + the shell

They compose on two levels:

The full pokemon module — Pokemon (recipe).