Javascript (Client-side)

schematic-js is a client-side JavaScript SDK for tracking event-based usage, identifying users, and checking flags using Schematic.

Install

$
npm install @schematichq/schematic-js
$
# or
$
yarn add @schematichq/schematic-js
$
# or
$
pnpm add @schematichq/schematic-js

Usage

You can use Schematic to identify users; after this, your subsequent track events and flag checks will be associated with this user.

A number of these examples use keys to identify companies and users. Learn more about keys here.

1
import { Schematic } from "@schematichq/schematic-js";
2
3
const schematic = new Schematic("your-api-key");
4
5
// Send an identify event
6
schematic.identify({
7
    keys: {
8
        id: "my-user-id",
9
    },
10
    traits: {
11
        anykey: "anyval",
12
    },
13
    company: {
14
        name: "My Company",
15
        keys: {
16
            id: "my-company-id",
17
        },
18
        traits: {
19
            location: "Atlanta, GA",
20
        },
21
    },
22
});
23
24
// Send a track event to record usage
25
schematic.track({ event: "query" });
26
// OR, Send a track event with a quantity to record multiple units of usage
27
schematic.track({ event: "query", quantity: 10 });
28
29
// Check a flag
30
await schematic.checkFlag({ key: "some-flag-key" });

By default, checkFlag will perform a network request to get the flag value for this user. If you’d like to check all flags at once in order to minimize network requests, you can use checkFlags:

1
import { Schematic } from "@schematichq/schematic-js";
2
3
const schematic = new Schematic("your-api-key");
4
5
schematic.identify({
6
    keys: { id: "my-user-id" },
7
    company: {
8
        keys: { id: "my-company-id" },
9
    },
10
});
11
12
await schematic.checkFlags();

Alternatively, you can run in websocket mode, which will keep a persistent connection open to the Schematic service and receive flag updates in real time:

1
import { Schematic } from "@schematichq/schematic-js";
2
3
const schematic = new Schematic("your-api-key", { useWebSocket: true });
4
5
schematic.identify({
6
    keys: { id: "my-user-id" },
7
    company: { keys: { id: "my-company-id" } },
8
});
9
10
await schematic.checkFlag("some-flag-key");
11
12
// Close the connection when you're done with the Schematic client
13
schematic.cleanup();

Fallback Behavior

The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

Flag Check Fallbacks

When checkFlag cannot reach Schematic, it uses fallback values in the following priority order:

1. Callsite fallback - fallback values can be provided directly in the checkFlag call
2. Initialization defaults - fallback values configured via flagCheckDefaults or flagValueDefaults options when initializing the SDK
3. Default value - Returns false if no fallback is configured

1
// Provide a fallback value at the callsite
2
const value = await schematic.checkFlag({ 
3
    key: "feature-flag", 
4
    fallback: true  // Used if API request fails
5
});
6
7
// Or configure defaults at initialization
8
const schematic = new Schematic("your-api-key", {
9
    flagValueDefaults: {
10
        "feature-flag": true,  // Used if API request fails and no callsite fallback
11
    },
12
    flagCheckDefaults: {
13
        "another-flag": {
14
            flag: "another-flag",
15
            value: true,
16
            reason: "Default value",
17
        },
18
    },
19
});

Event Queueing and Retry

When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:

• Events are queued in memory (up to 100 events by default, configurable via maxEventQueueSize)
• Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via maxEventRetries)
• Events are automatically flushed when the network connection is restored
• Events queued when the page is hidden are sent when the page becomes visible

WebSocket Fallback

In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as outlined above. The WebSocket will also automatically attempt to re-establish it’s connection with Schematic using an exponential backoff.

Troubleshooting

For debugging and development, Schematic supports two special modes:

Debug Mode

Enables console logging of all Schematic operations:

1
// Enable at initialization
2
const schematic = new Schematic("your-api-key", { debug: true });
3
4
// Or via URL parameter
5
// https://yoursite.com/?schematic_debug=true

Offline Mode

Prevents network requests and returns fallback values for all flag checks:

1
// Enable at initialization
2
const schematic = new Schematic("your-api-key", { offline: true });
3
4
// Or via URL parameter
5
// https://yoursite.com/?schematic_offline=true

Offline mode automatically enables debug mode to help with troubleshooting.

License

MIT

Support

Need help? Please open a GitHub issue or reach out to support@schematichq.com and we’ll be happy to assist.