Strata Docs

Quick start

Create a project

Go to strata.charisol.io, create a project, and import your design tokens from a Style Dictionary JSON or Figma file.

Get your project ID & token

Open the Publish & Sync tab on your project dashboard. Copy your project ID and generate a sync token.

Install the package

Run npm install @strata-ds/core. Works with React 18+, Next.js App Router, and Pages Router.

Wrap and use

Add StrataProvider at your app root, pass projectId, snapshotCdnBase, and syncToken, then call useComponents() anywhere inside.

Installation

# npm
npm install @strata-ds/core

# yarn
yarn add @strata-ds/core

StrataProvider setup

Wrap your root layout with StrataProvider. Pass your projectId, snapshotCdnBase, and syncToken. It polls every syncInterval ms (default 3000) and updates all consuming components without a reload.

Prop	Type	Default	Description
`syncEnabled`	boolean	false	Enable live polling from the Strata backend.
`syncUrl`	string	—	Legacy — base URL from your project dashboard. Prefer snapshotCdnBase + projectId instead.
`syncInterval`	number	3000	Polling interval in milliseconds.
`projectId`	string	—	Your Strata project ID. Required when using snapshotCdnBase.
`snapshotCdnBase`	string	—	CDN base URL for snapshot fetches. A single edge-cached request replaces 3 Lambda calls.
`syncToken`	string	—	Sync token from the Publish & Sync tab. Adds Authorization: Bearer to all sync requests.

💡 Get your projectId and generate a syncToken from the Publish & Sync tab at strata.charisol.io.

// app/layout.tsx  (Next.js App Router)
import { StrataProvider } from "@strata-ds/core";

export default function RootLayout({ children }) {
  return (
    <StrataProvider
      syncEnabled={true}
      projectId="YOUR_PROJECT_ID"
      snapshotCdnBase="https://cdn.strata.charisol.io"
      syncToken="pt_live_your_token_here"
    >
      {children}
    </StrataProvider>
  );
}

Using components with useComponents()

useComponents() returns a map of every component you defined in your Strata project, keyed by PascalCase name. Render them conditionally — they are undefined while the first sync is in flight.

"use client";
import { useComponents } from "@strata-ds/core";

function App() {
  const { Button, Navbar, Card } = useComponents();

  return (
    <>
      {Button && <Button onClick={() => console.log("clicked")}>Click me</Button>}
      {Card && <Card style={{ padding: "20px" }}>Card content</Card>}
    </>
  );
}

Web Components integration

If your app is not React-based, use the Web Components package. Register the elements once at startup, then use custom elements directly in HTML.

npm install @strata-ds/web-components

import { registerStrataElements, initStrataSync } from "@strata-ds/web-components";

registerStrataElements();

initStrataSync({
  projectId: "YOUR_PROJECT_ID",
  snapshotCdnBase: "https://cdn.strata.charisol.io",
  syncToken: "pt_live_your_token_here",
  syncEnabled: true,
  syncInterval: 3000,
});

Build-time vs runtime

Build-time sync

Compile tokens and components at deploy time. Ideal when release governance is strict.

Runtime sync

Poll every 3 seconds and apply updates live, including structural component changes.

Hooks reference

Hook	Returns	Description
`useComponents()`	`Record<string, React.ComponentType>`	Map of all registered PascalCase components.
`useComponent(name)`	`React.ComponentType \| null`	Single component by name.
`useStrata()`	`StrataContextType`	Full context: designSystem, syncStatus, lastSynced, forceSync, syncUrl, syncEnabled.
`useDynamicComponents()`	`ComponentRegistry`	Raw registry map before PascalCase normalisation.

TypeScript types

The Strata SDK is fully typed. All hooks and components export TypeScript definitions for complete IDE autocomplete and type safety.

interface DesignToken {
  name: string;            // e.g. "--color-brand-primary"
  value: string | number;  // e.g. "#3B82F6" or 16
  type: 'color' | 'spacing' | 'fontSize' | 'fontWeight' |
        'lineHeight' | 'shadow' | 'borderRadius' | 'other';
  unit?: string;
  comment?: string;
  category?: string;
}

interface ComponentNode {
  id: string;
  name: string;
  type: 'button' | 'input' | 'card' | 'nav' | 'other';
  properties: Record<string, string | number>;
  styles?: Record<string, string>;
  children?: ComponentNode[];
}

Debugging

Drop <StrataDebug /> anywhere inside StrataProvider during development. It renders a panel showing sync status, last synced timestamp, the sync URL, and all registered component names.

import { StrataDebug } from "@strata-ds/core";

// Anywhere inside <StrataProvider>
<StrataDebug />