Skip to content
SparkleTree SparkleTree Docs

SparkletreeProviderProps

Defined in: react/src/provider.tsx:73

@sparkletree/react — React bindings for the SparkleTree SDK.

Two layers, and the boundary between them is the whole design:

  • PRIMITIVES (StreamText, useIsland) live in npm. They speak the wire, own the choreography, and carry the trust chrome structurally. They are ours to patch.
  • COMPONENTS (Hero, Cta) also ship as copy-paste source through sparkletree add. Those copies are the customer’s, and they are wire-ignorant by construction — no event names, no protocol versions, no timing constants — so a protocol change never obliges a customer to re-copy anything.

Properties

Section titled “Properties”

apiBase?

Section titled “apiBase?”

optional apiBase?: string

Defined in: react/src/provider.tsx:76

Optional when publishableKey is given; when both are set, the explicit prop wins (the documented escape hatch for self-hosted bases).

children

Section titled “children”

children: ReactNode

Defined in: react/src/provider.tsx:145

context?

Section titled “context?”

optional context?: Record<string, unknown>

Defined in: react/src/provider.tsx:103

Extra context merged over the automatically collected signals. Anything here wins — a host that knows its own audience knows better than our inference does.

Must be JSON-serializable (it is sent on the wire as JSON regardless). Identity is derived from CONTENT, so an inline context={{ ... }} object re-created on every parent render is fine: structurally equal context does not re-open any island’s stream.

fetchImpl?

Section titled “fetchImpl?”

optional fetchImpl?: (input, init?) => Promise<Response>

Defined in: react/src/provider.tsx:146

MDN Reference

Parameters

Section titled “Parameters”
input
Section titled “input”

URL | RequestInfo

init?
Section titled “init?”

RequestInit

Returns

Section titled “Returns”

Promise<Response>

mintToken?

Section titled “mintToken?”

optional mintToken?: MintTokenSource

Defined in: react/src/provider.tsx:144

A signed mint token, or a function returning one (sync or async).

Optional. Without it fragments still mint, gated on the request Origin — which authenticates a browser and nothing else. A token is issued by YOUR backend (POST https://app.sparkletree.io/api/embed/v1/fragments/mint-token with an st_ API key; this is the app host, not your embed apiBase) and is what actually pins mint spend to your org.

Prefer the function form: tokens expire after 300 seconds, and a page open longer than that would otherwise echo a dead one. Define it outside render (or wrap it in useCallback) — like fetchImpl, a new identity each render re-renders this provider’s consumers.

organizationId?

Section titled “organizationId?”

optional organizationId?: string

Defined in: react/src/provider.tsx:78

Optional when publishableKey is given; explicit prop wins.

publishableKey?

Section titled “publishableKey?”

optional publishableKey?: string

Defined in: react/src/provider.tsx:92

st_pk_live_… / st_pk_test_… from the dashboard.

The publishable key is a signed credential minted in the dashboard. Every stream request must carry it. Test keys (st_pk_test_) work on their own for development; live keys (st_pk_live_) only work from an origin registered to your organization. Treat it like any client-side key: it is visible in page source, so protection comes from the origin registry and rate limits; rotate it from the dashboard if it leaks.

Its payload also fills organizationId and apiBase (decoded locally, zero network); explicit props win over the payload for addressing.

serverContext?

Section titled “serverContext?”

optional serverContext?: ServerContext

Defined in: react/src/provider.tsx:118

The visitor context your server used to read copy for this page view: pass getIslandCopy(...).context (from @sparkletree/core/server or @sparkletree/react/server), or deriveServerContext(headers) when the page does not read copy.

For this page view the browser then sends the server’s device type, time of day, time zone and language instead of reading its own, and pins the variant the server read for before any island’s stream opens. Its streams and the copy they cache then use the key the server reads, so the next server read for a visitor like this one finds it.

Values in context still win. Leave it unset and nothing changes.

storage?

Section titled “storage?”

optional storage?: Storage

Defined in: react/src/provider.tsx:157

Where the viewer’s trust-chrome preference is persisted. Defaults to window.localStorage.

Injectable because ambient storage is not reliably there: a consent manager may gate it, a privacy mode may throw on access, and Node 18+ exposes a same-named global that shadows the real one — under Node 26 + jsdom, window.localStorage is undefined outright. A preference that silently cannot be stored is a viewer whose choice we ignore.

viewKey?

Section titled “viewKey?”

optional viewKey?: string

Defined in: react/src/provider.tsx:128

Identifies the page view, for a provider that outlives page views (an app-root provider across client-side navigation): pass something that changes once per view, such as the route path. A new value starts a new page view before any island below opens its stream: variant pins, what each slot showed and which impressions were recorded all start fresh, and islands still on screen may show the new view’s copy. With serverContext the server read’s view is used when this is unset.