Install

npm install @arlioz/flagship-node @arlioz/flagship

@arlioz/flagship is a peer dependency.

Quick Start

Standalone

import { FlagShipServer } from '@arlioz/flagship-node'

const flagship = new FlagShipServer({
  apiKey: 'flg_production_...',
  baseUrl: 'https://your-api.com/api',
})

await flagship.waitUntilReady()

const darkMode = flagship.getSync('dark-mode', false)
const limit = flagship.getSync('upload-limit', 10)

Express middleware

import express from 'express'
import { FlagShipServer, flagshipMiddleware } from '@arlioz/flagship-node'

const flagship = new FlagShipServer({ apiKey: 'flg_production_...' })
await flagship.waitUntilReady()

const app = express()
app.use(
  flagshipMiddleware(flagship, {
    getUserId: (req) => req.user?.id,
    getAttributes: (req) => ({ plan: req.user?.plan }),
  }),
)

app.get('/', (req, res) => {
  // req.flags is populated by the middleware
  res.json({ flags: req.flags })
})

API

FlagShipServer

| Method | Return | Description | | -------------------------------- | ------------------------------ | ----------------------------- | | waitUntilReady() | Promise<void> | Wait for initial flag fetch | | get<T>(key, defaultValue?) | Promise<T> | Async flag value | | getSync<T>(key, defaultValue?) | T | Sync from cache | | getAllSync() | Record<string, any> | All cached flags | | fetchFlags() | Promise<Record<string, any>> | Force refresh | | identify(userId, attributes?) | Promise<void> | Update user context + refetch | | close() | void | Stop polling and clean up |

flagshipMiddleware

flagshipMiddleware(server, {
  requestProperty?: string,    // default: 'flags'
  getUserId?: (req) => string | undefined,
  getAttributes?: (req) => Record<string, any>,
})

Attaches evaluated flags to req.flags (or custom property) on every request.

Compatibility

• Node.js >= 18
• Works with Express, Fastify, Koa, and any Connect-compatible framework

License

MIT — Arlioz