@statisfy/portal-react

Embeddable customer-portal shell for React: native email-OTP auth, an account switcher, and the project module.

Digital Worker chat, onboarding and tool-call forms are a separate package — @statisfy/ai-react. Install both if you want both; they share one provider and one theme.

Install

npm install @statisfy/portal-react react react-dom

react and react-dom (18 or 19) are peer dependencies you provide. @statisfy/sdk-core is also a peer, and npm installs it for you — it must resolve to a single copy, which is why it is a peer rather than a bundled dependency. Everything else is bundled.

Usage

Wrap your app once in <StatisfyProvider>, then render components anywhere beneath it. Connection and auth live on the provider; components take only their own display props.

import {
  PortalAuthGate,
  ProjectModule,
  StatisfyProvider
} from '@statisfy/portal-react'
import '@statisfy/portal-react/styles.css' // required — import once

export function Portal() {
  return (
    <PortalAuthGate baseUrl="https://api.statisfy.com" portalId="<uuid>">
      <StatisfyProvider
        publishableKey="pk_live_…"
        getToken={async () => '<bearer>'}
      >
        <ProjectModule />
      </StatisfyProvider>
    </PortalAuthGate>
  )
}

A component rendered outside <StatisfyProvider> throws, rather than silently sending unauthenticated requests. The stylesheet import is required; without it the portal renders unstyled.

If you also render @statisfy/ai-react, import both stylesheets and keep ONE <StatisfyProvider> around both — the two packages share the same provider, so nesting a second one is never necessary.

Build-time runtime config (/vite)

Portals built by the Statisfy platform inject their commit's portal.runtime.json into the page. The Vite plugin that does it ships in @statisfy/sdk-core, which this package already pulls in as a peer:

// vite.config.ts
import { statisfyPortalRuntime } from '@statisfy/sdk-core/vite'

export default { plugins: [statisfyPortalRuntime()] }

Theming

Everything visual is reachable from host CSS through two seams: the --dw-* variable table and the data-dw-part anatomy attributes. Both work with plain, normal declarations — !important is not needed and must not be used, because all SDK CSS ships inside @layer and an unlayered author rule outranks every layer.

/* space-separated RGB triplets, not rgb() or hex */
:root { --dw-primary: 13 148 136; }

/* or target one part */
[data-dw-part='task-row'] { border-radius: 0; }

Dark mode is opt-in via data-dw-theme="dark" (or "auto" to follow the OS) on the root element — an embedded widget should match the page it is mounted in, not the visitor's OS.

The full token table, the dark palette, the documented-stable part names and the worked examples live in @statisfy/sdk-core's README — the package that owns the token layer. The contract is identical for every Statisfy SDK package, so it is documented once rather than drifting in three copies.

License

MIT