AirshipJS

A feature flagging library for Node.js, React, and Javscript

AirshipJS is an open-source feature flagging library. Feature flags allows developers to deliver features quickly and safely with fine-grained control over who sees each feature. Airship can be configured locally without setting up new services or making network requests.

This library aims to make feature flagging easy to set up by being:

• Declarative: The logic of who sees what feature is declared and managed in one centralized place (instead of scattered throughout code) to make feature flags simpler to predict and debug.
• Performant: Feature flags are resolved locally at runtime without incurring the cost of a network request.
• High Resolution: Allow targeting of any audience using a mixture of strategies, including individual users, %s of populations, groups, non-user entities, and more.
• Developer-friendly: Exposes intuitive functions to developers that abstract away the unnecessary complexity of feature gating logic.

This library is a standalone solution for feature flagging, but also powers Airship Cloud, a networked version of Airship with a UI for managing flags and additional features for teams.

Content

• 01 Installation
• 02 Key Concepts
• 03 Configuring Flags
• 04 Usage
• 05 Compatibility
• 06 Additional Resources

01 Installation

Airship is available on public package repositories.

Importing AirshipJS

// In CommonJS
var Airship = require('airship-js')

// In ES2015 modules
import Airship from 'airship-js'

02 Key Concepts

In Airship, feature flags control traffic to generic objects (called entities). The most common type for entities is User, but they can also be other things (i.e. Page, Group, Team, App, etc.). By default, all entities have the type User.

Learn about other concepts here.

03 Configuring Flags

Feature flags are initialized by called Airship.configure(options). All flags are declared with a set of rules in a standard format that define how users / entities are targeted. These flagging rules can be defined in 2 ways:

• Configuring Airship Core (free): Define rules in a standard JSON format passed directly to the configure function. The flag configurations can be stored in a flat JSON file, exported from a dashboard you create, defined inline, etc.
• Configuring Airship Cloud (paid): Flag configurations are created and hosted on Airship through a UI console that also adds additional features including: multivariate flags, groups, real-time updates, A/B testing, multiple populations, dynamic payloads, history tracking, and more.

04 Usage

Once flags are configured, a few simple functions resolve whether a user has access to a feature. A flag has several "gating" functions that can be used to resolve feature access permissions. The most commonly used one is flag.isEnabled().

var user = {id: 1} // the simplest acceptable user only consists of a unique ID

var flag = Airship.flag('bitcoin-pay')
console.log(
  'Bitcoin payments are',
  flag.isEnabled(user) ? 'enabled' : 'disabled'
)
// => Bitcoin payments are enabled

if (flag.isEnabled(user)) {
  // show Bitcoin payment button
}

To see the rest of the Airship API, check out the full API Reference.

AirshipJS for React

AirshipJS also includes a toolkit of React components to make feature flagging in React applications easy.

Simple Example

<Flag flag="bitcoin-pay" case="on" entity={user}>
  <BitcoinPaymentButton />
</Flag>

Another Example

<FlagProvider flagConfig={flagConfig} entity={user}>
  <FlagSwitch flag="bitcoin-pay">
    <Flag case="on">
      <BitcoinPaymentButton />
    </Flag>
    <Flag case="off">
      <PaypalPaymentButton />
    </Flag>
  </FlagSwitch>
</FlagProvider>

See AirshipJS for React for full documentation.

05 Compatibility

AirshipJS supports a wide range of JavaScript platforms, including NodeJS, browsers, and React apps.

06 Additional Resources

• Concepts
• API Reference

Migrating from v1?

If you were using airship-js v1 or airship-nodejs v1, note that they have been merged into this package. This package is backward compatible. Once you install the new airship-js, all you need change is how you import Airship.

import Airship from 'airship-js/compat'

License

Release under the MIT License