JavaScript
Install the latest version
Use your favorite package manager to install @prefab-cloud/prefab-cloud-js
npm | github
- npm
- yarn
npm install @prefab-cloud/prefab-cloud-js
yarn add @prefab-cloud/prefab-cloud-js
TypeScript types are included with the package.
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.
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
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() ) |