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.

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("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();

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.