Schematic Frontend SDK Integration

Schematic Frontend SDK Integration

Overview

Schematic's frontend SDKs let you check feature flags, track usage, and identify users client-side. They use a publishable key (not a secret API key) and are safe to expose in browser code.

Three packages:

• @schematichq/schematic-js — Core JS client (framework-agnostic)
• @schematichq/schematic-react — React hooks and provider
• @schematichq/schematic-vue — Vue composables and plugin

Framework Detection

Show examples for the framework the user is working with. If unclear, ask whether they're using React, Vue, or plain JS.

Installation

React:

npm install @schematichq/schematic-react

Vue:

npm install @schematichq/schematic-vue

Plain JS:

npm install @schematichq/schematic-js

Setup

React — SchematicProvider

Wrap your app (or a subtree) with SchematicProvider:

import { SchematicProvider } from "@schematichq/schematic-react";

function App() {
  return (
    <SchematicProvider publishableKey={process.env.NEXT_PUBLIC_SCHEMATIC_PUBLISHABLE_KEY}>
      <YourApp />
    </SchematicProvider>
  );
}

Vue — SchematicPlugin

Register the plugin in your app entry:

import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";
import App from "./App.vue";

const app = createApp(App);
app.use(SchematicPlugin, {
  publishableKey: import.meta.env.VITE_SCHEMATIC_PUBLISHABLE_KEY,
});
app.mount("#app");

Plain JS — Direct Client

import { Schematic } from "@schematichq/schematic-js";

const schematic = new Schematic("your-publishable-key");

Identify Users

Call identify after login or when user context changes. This sets the context for all subsequent flag checks.

Important: Before using identify, you must configure how users and companies are identified in Schematic. See Key Management for details on setting up user and company keys.

Ask the user: What keys have you configured in Schematic for identifying users and companies? (e.g., app_id, internal_id, stripe_customer_id, etc.)

React

import { useSchematicEvents } from "@schematichq/schematic-react";

function LoginHandler() {
  const { identify } = useSchematicEvents();

  const onLogin = (user) => {
    identify({
      // Use the keys you configured in Schematic (e.g., "id", "email", etc.)
      keys: { id: user.id },
      company: {
        // Use the keys you configured in Schematic for companies
        keys: { id: user.companyId },
        name: user.companyName,
      },
    });
  };

  return <button onClick={() => onLogin(currentUser)}>Log in</button>;
}

Vue

import { useSchematicEvents } from "@schematichq/schematic-vue";

const { identify } = useSchematicEvents();

function onLogin(user) {
  identify({
    // Use the keys you configured in Schematic (e.g., "id", "email", etc.)
    keys: { id: user.id },
    company: {
      // Use the keys you configured in Schematic for companies
      keys: { id: user.companyId },
      name: user.companyName,
    },
  });
}

Plain JS

schematic.identify({
  // Use the keys you configured in Schematic (e.g., "id", "email", etc.)
  keys: { id: "user-id" },
  company: {
    // Use the keys you configured in Schematic for companies
    keys: { id: "company-id" },
    name: "Acme Corp",
  },
});

Check Feature Flags

React — useSchematicFlag

import { useSchematicFlag } from "@schematichq/schematic-react";

function FeatureGate() {
  const isEnabled = useSchematicFlag("feature-flag-key");

  if (!isEnabled) return null;
  return <NewFeature />;
}

With fallback value:

const isEnabled = useSchematicFlag("feature-flag-key", { fallback: false });

React — useSchematicEntitlement

For metered features with usage limits:

import { useSchematicEntitlement } from "@schematichq/schematic-react";

function UsageDisplay() {
  const { value, featureUsage, featureAllocation, featureUsageExceeded } = useSchematicEntitlement("api-calls");

  return (
    <div>
      {value ? "Active" : "Limit reached"}
      <span>{featureUsage} / {featureAllocation} used</span>
    </div>
  );
}

Vue — useSchematicFlag

<script setup>
import { useSchematicFlag } from "@schematichq/schematic-vue";

const isEnabled = useSchematicFlag("feature-flag-key");
</script>

<template>
  <NewFeature v-if="isEnabled" />
</template>

Vue — useSchematicEntitlement

<script setup>
import { useSchematicEntitlement } from "@schematichq/schematic-vue";

const { value, featureUsage, featureAllocation } = useSchematicEntitlement("api-calls");
</script>

<template>
  <div>
    <span>{{ featureUsage }} / {{ featureAllocation }} used</span>
  </div>
</template>

Plain JS

const isEnabled = await schematic.checkFlag({ key: "feature-flag-key" });

Track Events

React

import { useSchematicEvents } from "@schematichq/schematic-react";

function ActionButton() {
  const { track } = useSchematicEvents();

  return (
    <button onClick={() => track({ event: "api-call", quantity: 1 })}>
      Make API Call
    </button>
  );
}

Vue

import { useSchematicEvents } from "@schematichq/schematic-vue";

const { track } = useSchematicEvents();

function onAction() {
  track({ event: "api-call", quantity: 1 });
}

Plain JS

schematic.track({ event: "api-call", quantity: 1 });

Loading States

React — useSchematicIsPending

import { useSchematicIsPending } from "@schematichq/schematic-react";

function App() {
  const isPending = useSchematicIsPending();

  if (isPending) return <Spinner />;
  return <MainContent />;
}

Vue — useSchematicIsPending

<script setup>
import { useSchematicIsPending } from "@schematichq/schematic-vue";

const isPending = useSchematicIsPending();
</script>

<template>
  <Spinner v-if="isPending" />
  <MainContent v-else />
</template>

WebSocket Mode

WebSocket mode provides real-time flag updates without polling. It maintains a persistent connection and pushes flag changes instantly, with automatic reconnection using exponential backoff.

React and Vue: WebSocket mode is enabled by default. You can explicitly enable it if needed:

React

<SchematicProvider publishableKey={key} useWebSocket={true}>
  <App />
</SchematicProvider>

Vue

app.use(SchematicPlugin, {
  publishableKey: key,
  useWebSocket: true,
});

Plain JS

Highly recommended: Enable WebSocket mode for real-time updates:

const schematic = new Schematic("key", { useWebSocket: true });

Advanced Options

Debug Mode

Logs all flag evaluations and events to the console:

// React
<SchematicProvider publishableKey={key} debug={true}>

// Vue
app.use(SchematicPlugin, { publishableKey: key, debug: true });

// JS
new Schematic("key", { debug: true });

Offline Mode

Disables network requests, uses flag defaults:

// React
<SchematicProvider publishableKey={key} offline={true}>

// Vue
app.use(SchematicPlugin, { publishableKey: key, offline: true });

// JS
new Schematic("key", { offline: true });

Flag Value Defaults

Fallback values when the API is unreachable:

// React
<SchematicProvider publishableKey={key} flagValueDefaults={{ "my-flag": true }}>

// Vue
app.use(SchematicPlugin, { publishableKey: key, flagValueDefaults: { "my-flag": true } });

// JS
new Schematic("key", { flagValueDefaults: { "my-flag": true } });

Available Hooks / Composables

Hook / Composable	Returns	Description
useSchematicFlag(key)	boolean (React) / Ref<boolean> (Vue)	Check a single flag
useSchematicEntitlement(key)	{ value, featureUsage, featureAllocation, featureUsageExceeded, ... }	Check entitlement with usage
useSchematicEvents()	{ identify, track }	Send identify/track events
useSchematicIsPending()	boolean / Ref<boolean>	True while initial data loads
useSchematicContext()	{ context, setContext }	Read/update evaluation context
useSchematic()	{ client }	Access the raw Schematic client

Key Gotchas

1. Use publishable key — not the secret API key. Publishable keys are safe for client-side code
2. Call identify before checking flags — flags evaluate against the identified user/company context
3. Vue refs auto-unwrap in templates — useSchematicFlag returns a Ref<boolean>, but Vue templates unwrap it automatically
4. SSR considerations — flag checks return defaults during server rendering; hydration picks up real values client-side