Browse docs

API

createStift

ReactVanilla

Builds the headless instance. Everything declarative — locales, namespaces, detection order, persisted state — arrives via the generated runtime; the options below supply only what can't be serialized.

createStift(options): Stift
createStiftApp(options): Promise<{ stift, boot }>

Options

...runtime

  • Type: spread of createStiftRuntime() (generated config + catalog + source).
  • Required. The normalized config, always first.

persister

  • Type: PersisterAdapter — offline pack store (OPFS/IndexedDB).
  • Optional, but offline packs need it. createStiftApp also accepts a factory (() => PersisterAdapter | Promise<PersisterAdapter>), resolved once — use createBestEffortPersister unless you have a reason not to.

state

  • Type: { prefix?: string; storage?: 'webStorage' | 'cookie' | 'none' }
  • Optional — default: { prefix: '__stift_', storage: 'webStorage' }. Persisted user state (locale + param/unit overrides), read synchronously at construction so there is no flash. Normally set in stift.config.ts, not here.

detectors

  • Type: { custom: Detector[] }
  • Optional. Reserved runtime-slot detectors, registered here rather than in config.

hooks

  • Type: StiftRuntimeHooks, including onUpdateAvailable and onError.
  • Optional. Lifecycle hooks — the missing-key reporter and the update signal live here.

Loose options

Config overrides applied per-instance before normalization. Prefer stift.config.ts; reach for these in tests and SSR harnesses that need a shaped instance.

createStiftApp and boot

Same options as createStift. boot({ locale?, critical? }) runs detectLocale → setLocale → initialize (initialize unawaited, so first paint stays off the network) and returns the active locale.

stift.config is the frozen effective config — security.staticKey is never included.

Examples

import { createStiftApp } from '@secundus-studio/stift-core'
import { createStiftRuntime } from 'virtual:stift/runtime'
import { createBestEffortPersister } from '@secundus-studio/stift-persisters'

export const { stift, boot } = await createStiftApp({
  ...createStiftRuntime(),
  persister: createBestEffortPersister,
})

Next