JavaScript

Install the latest version

Use your favorite package manager to install @prefab-cloud/prefab-cloud-js npm | github

npm

npm install @prefab-cloud/prefab-cloud-js

yarn

yarn add @prefab-cloud/prefab-cloud-js

TypeScript types are included with the package.

tip

If you're using React, consider using our React Client instead.

Initialize the client

Initialize prefab with your api key:

import { prefab } from "@prefab-cloud/prefab-cloud-js";

const options = {
  apiKey: "YOUR_CLIENT_API_KEY",
};

await prefab.init(options);

prefab.init will request the calculated feature flags for the provided context as a single HTTPS request. If you need to check for updates to feature flag values, you can learn more about polling below.

You aren't required to await the init -- it is a promise, so you can use .then, .finally, .catch, etc. instead if you prefer.

tip

While prefab is loading, isEnabled will return false, get will return undefined, and shouldLog will use your defaultLevel.

Feature Flags

Now you can use prefab's feature flag evaluation, e.g.

if (prefab.isEnabled('cool-feature') {
  // ... this code only evaluates if `cool-feature` is enabled for the current context
}

You can also use get to access the value of non-boolean flags

const stringValue = prefab.get("my-string-flag");

Context

Context accepts an object with keys that are context names and key value pairs with attributes describing the context. You can use this to write targeting rules, e.g. segment your users.

import { prefab, Context } from "@prefab-cloud/prefab-cloud-js";

const options = {
  apiKey: "YOUR_CLIENT_API_KEY",
  context: new Context({
    user: { key: "abcdef", email: "test@example.com" },
    device: { key: "hijklm", mobile: true },
  }),
};

await prefab.init(options);

poll()

After prefab.init(), you can start polling. Polling uses the context you defined in init by default. You can update the context for future polling by setting it on the prefab object.

// some time after init
prefab.poll({frequencyInMs: 300000})

// we're now polling with the context used from `init`

// later, perhaps after a visitor logs in and now you have the context of their current user
prefab.context = new Context({...prefab.context, user: { email: user.email, key: user.trackingId })

// future polling will use the new context

Dynamic Config

caution

JavaScript is a Client SDK and does not receive Config. Learn more about Client SDKs

Dynamic Logging

shouldLog allows you to implement dynamic logging. It takes the following properties:

property	type	example	case-sensitive
loggerName	string	my.corp.widgets.modal	Yes
desiredLevel	string	INFO	No
defaultLevel	string	ERROR	No

If you've configured a level value for loggerName (or a parent in the dot-notation hierarchy like "my.corp.widgets") then that value will be used for comparison against the desiredLevel. If no configured level is found in the hierarchy for loggerName then the provided defaultLevel will be compared against desiredLevel.

If desiredLevel is greater than or equal to the comparison severity, then shouldLog returns true. If the desiredLevel is less than the comparison severity, then shouldLog will return false.

Example usage:

const desiredLevel = "info";
const defaultLevel = "error";
const loggerName = "my.corp.widgets.modal";

if (shouldLog({ loggerName, desiredLevel, defaultLevel })) {
  console.info("...");
}

If no log level value is configured in Prefab for "my.corp.widgets.modal" or higher in the hierarchy, then the console.info will not happen. If the value is configured and is INFO or more verbose, the console.info will happen.

Testing

In your test suite, you should skip prefab.init altogether and instead use prefab.setConfig to set up your test state.

it("shows the turbo button when the feature is enabled", () => {
  prefab.setConfig({
    turbo: true,
    defaultMediaCount: 3,
  });

  const rendered = new MyComponent().render();

  expect(rendered).toMatch(/Enable Turbo/);
  expect(rendered).toMatch(/Media Count: 3/);
});

Reference

prefab Properties

property	example	purpose
isEnabled	prefab.isEnabled("new-logo")	returns a boolean (default false) if a feature is enabled based on the current context
get	prefab.get('retry-count')	returns the value of a flag or config evaluated in the current context
loaded	if (prefab.loaded) { ... }	a boolean indicating whether prefab content has loaded
shouldLog	if (prefab.shouldLog(...)) {	returns a boolean indicating whether the proposed log level is valid for the current context
poll	prefab.poll({frequencyInMs})	starts polling every frequencyInMs ms.
stopPolling	prefab.stopPolling()	stops the polling process
context	prefab.context = new Context(...)	get or set the current context (after init())