some-typescript v3.0.0
Flagger SDK
An opensource JavaScript SDK for feature flagging(feature gating, feature toggles) for browser and nodejs
Adding a dependency
Make sure that all new dependencies are listed in rollup.config.js
Build
Build consist of two phases:
- tsc compiles *.ts to ES2017 target. These files are in
temp
folder - rollup creates 3 bundles(umd, ES2017, CommonJS) from that compiled code. Also, rollup overrides VERSION and SDK_NAME accordingly
note: React wrapper for Flagger is no longer a part of this repo
Features
- Blazing fast, requires only 1 backend call to decide what flag to show
- Highly customizable
- Sampling(canary release) and multivariate A/B testing with custom filters
- Auto-updatable configuration(via SSE)
- Records usage analytics as well as custom events
- white- and blacklisting
- 2 level entity support (Manager-Employee, Client-Company)
Quick start
Install dependency
npm i flagger
Import flagger to you application
// In CommonJS
var Flagger = require('flagger')
// In ES2015 modules
import Flagger from 'flagger'
Flagger SDK requires a config to decide what flag to show. Init flagger client with a config by requestion it either from Airship server or provide it from your custom source
// Airship server
await Flagger.init({env: 123})
// Or manually
await Flagger.init({env: 123, sourceURL: 'someserver.com'})
Use Flagger
to get flag*
and control flow of your application code. Flag
requires an Entity
(object with id
) to work. All flag functions are idempotent
const user = {id: '1'}
const isEnabled = Flagger.flagIsEnabled('new-dashboard', user)
if (isEnabled)) {
// show new dashboard
} else {
// show old dashboard
}
You can pass Entity
to the flagger instance to not specify it in every flag function
Flagger.setEntity({id: '1'})
How it works
Flagger loads config(for example from an Airship server) and then resolves Entity
and flag name into a Flag
.
Key concepts
The core of the flagger takes a flaggerConfig
, entity
and flagName
and resolves it to a Flag
. Flag
has multiple purposes:
- toggle on/off features
- provide an ability to do A/B testing (multivariative features)
- get flag payload
- undestand whether current entity is sampled or not
FAQ
How many backend call does
Flagger
do?It only requires 1 call to load config and from then every call to API do not require a call to remote server
How can I update flag config on user's device?
When user open your app, SDK is initializing with new config. When user is already using your app, Flagger holds an SSE connection from server to push new config. This invariant makes sure all users has up to date config
How can I know which version of a flag was shown to a user?
Flagger automatically gathers this data(we call it ingestion data) and sends it to the `Backend`
Does flag version idempotent? Will the same user see the same feature when the page is updated?
Yes
API
Glossary
Flagger - is a singleton object. use .init()
function at your app initialization and then just import it whenever you want.
Entity - object with 1 required field: id
. Example:
{
"id": 90843823,
"name": "Kyle Stroman",
"attributes": {
"jobTitle": "Internal Intranet Administrator",
"email": "kyle62@herzogrobelandebert.com",
...
"country": "South Korea"
},
"type": "User",
"group": {
"attributes": {
"emailDomain": "herzogrobelandebert.com",
...
"country": "Greece"
},
"id": 84617314,
"name": "Herzog, Robel and Ebert",
"type": "Company"
}
}
Flag - multipurpose core entity of the Flagger
SDK. It helps you with toggling features on/off and deciding, for example, which color of a button to show to what kind of user.
Filter - a child of a subpopulation. You can treat it like a where
clause in SQL. It helps to filter out entities by their attributes
Backend - the server which serves Flagger SDK a config, push new config via SSE and takes ingestion data. Could be provided by AirshipHQ(paid) or you can deploy your own
Tests
npm test
Licence
MIT
4 years ago