Backstage Local

A local development config file provider for Backstage.

Backstage is a headless environment & feature flag library that isn't tied to any specific service or format. It's a React based library that focuses on being easy to use and simple to integrate with any (and multiple) feature providers.

This provider is designed to be used in conjunction with other providers as it is returns an empty config in production builds.

Usage

If you haven't added Backstage to your project yet, install the main package.

npm i @softwareimaging/backstage --save

To get started with this provider, add it to your project also.

npm i @softwareimaging/backstage-local --save

Set up a file in your source code to export your development config from. This could be a js, ts or even JSON file - whatever works best for your workflow. Think carefully if you want to commit this. Add it to your .gitignore if you want to keep it private.

// backstage.local.js
const config = {
  variables: {
    apiKey: 'X-API-123456789',
    name: 'Backstage'
  },
  flags: {
    banner: true,
    promotion: true
  }
}

export default config

Import your config and supply it to the provider configuration. See the main library documentation for more information about using this in React. If you want your development settings to override other providers, make sure that your priorities reflect that. Higher number means a higher priority which means that it overrides other values with the same key from other providers.

// backstage-provider.jsx
import { Backstage } from '@softwareimaging/backstage'
import LocalProvider from '@softwareimaging/backstage-local'
import config from './backstage.local'

const BackstageProvider = ({ children }) => {
  const providers = [
    LocalProvider(1, { config }) // A higher priority
  ]

  return <Backstage providers={providers}>{children}</Backstage>
}

Use with TypeScript

It's recommend for TypeScript projects to use an interface to define the known options for your configuration for all of the type-safe-goodness that comes with TypeScript.

Firstly, define your config interface.

// backstage-config.ts
export interface MyConfig extends BackstageConfig {
  variables: {
    apiKey: string
    name: string
  }
  flags: {
    banner: boolean
    promotion: boolean
  }
}

export type Variables = keyof MyConfig['variables']
export type Flags = keyof MyConfig['flags']

It's also worth defining an extra export of your possible variable & flag names. This will make typing your hook calls have less boilerplate.

While that may look a bit weird, it is simply just a type represents the keys in the object. In the example above Variables is equal to 'apiKey' | 'name' and Flags is equal to 'banner' | 'promotion'.

To use this in your components, add the type to your hook calls.

import { useFlag } from '@softwareimaging/backstage'
import { Flags } from './backstage-config'
const Text = () => {
  const promotion = useFlag<Flags>('promotion') // <- This key is typechecked.
  return promotion ? <p>Discount: £10!</p> : <p>Normal pricing: £100</p>
}

In the context of this provider, if you want your local settings to have all of the settings in your config, just make your config object comply to the interface you just wrote.

// backstage.local.ts
import { MyConfig } from './backstage-config'
const config: MyConfig = {
  variables: {}, // <- This will fail, needs every settin
  flags: {
    promotion: true,
    banner: true
  }
}

If you want it to especially be an override of another provider, then make sure you have the object be a partial version of the interface.

// backstage.local.ts
import { MyConfig } from './backstage-config'
const config: Partial<MyConfig> = {
  variables: {}, // <- This is fine now.
  flags: {}
}