@financial-times/dotcom-ui-flags
v11.2.1
Published
This package provides methods for integrating flags data into your server-side rendered pages and safely retrieving it again in the browser.
Downloads
2,313
Maintainers
robgodfrey
robertboulton
seraph2000
hamza.samih
notlee
emmalewis
aendra
the-ft
rowanmanning
chee
alexwilsonKeywords
Readme
@financial-times/dotcom-ui-flags
This package provides methods for integrating flags data into your server-side rendered pages and safely retrieving it again in the browser.
Getting started
This package is compatible with Node 12+ and is distributed on npm.
npm install --save @financial-times/dotcom-ui-flagsAfter installing the package you can use it to embed flags data into your pages on the server-side. This data can then be retrieved and used in your client-side code using the included flags client.
Server-side integration
If you are using React to render your app you should use the FlagsEmbed component to integrate the flags data with your pages:
import { FlagsEmbed } from '@financial-times/dotcom-ui-flags'
export default (props) => (
<html>
<head>
<meta charSet="utf-8" />
<title>My Amazing Website</title>
</head>
<body>
...
<FlagsEmbed flags={props.flagsData} />
</body>
</html>
)Otherwise you can insert a JSON formatted string into a <script> element with an ID of page-kit-flags-embed. You can use the .formatFlagsJSON() method to help with this.
const { formatFlagsJSON } = require('@financial-times/dotcom-ui-flags/server')
function page() {
return `<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>My Amazing Website</title>
</head>
<body>
...
<script type="application/json" id="page-kit-flags-embed">
${formatFlagsJSON(flagsData)}
</script>
</body>
</html>`
}Client-side integration
Once you are delivering the flags data with your pages you can use the flags client in your client-side code. The flags client provides methods for safely retrieving the status of individual flags.
import * as flags from '@financial-times/dotcom-ui-flags'
const flagsClient = flags.init()
if (flagsClient.get('myAmazingFeature')) {
...
}Client-side API
init()
Initialises and returns a new flags client which can be used to safely access the status of individual flags.
loadFlags()
Finds and parses the formatted flags data embedded in the page and returns the flags data object if successful.
Please note the formatted flags data must be present in a <script> element with an ID of page-kit-flags-embed.
Server-side API
formatFlagsJSON(flagsData: object)
Returns a serialised JSON string representing the given data. This will filter out any properties with a falsey value to reduce the amount of data to send to and parse on the client-side.
Please note The data returned by this method should be inserted into a <script> element with an ID of page-kit-flags-embed.
Flags client API
get(flag: string)
Returns the status for the requested flag. If the flag is not found or has been filtered out this will return undefined
getAll()
Returns all flags data.
Please note that the flags data object is frozen so it cannot be modified.