Nest.js SDK
Integrate FlagSync feature flags into Nest.js applications.
Overview
The @flagsync/nest-sdk
integrates into Nest.js applications for server-side feature management and event tracking—ideal for backend services and APIs.
Installation
Install the SDK with your preferred package manager:
Quickstart
A basic example of using the SDK in a Nest.js application—set up the SDK in two steps:
Configure the Module
Import FlagSyncModule
in your app.module.ts
:
Inject the Client
Use @InjectFlagSync()
to inject the client into a Provider (e.g., service, controller, etc.):
Initialization
The SDK leverages the onModuleDestroy
lifecycle event to automatically destroy the FsClient
on application shutdown, releasing connections to FlagSync’s servers.
To ensure proper cleanup, call enableShutdownHooks
during application startup. See the Nest.js documentation for Application Shutdown
Get Your SDK Key
Find your server-side SDK key in your workspace settings. Keep server-side keys private to protect flag rules.
Initialize the SDK
Initialize the SDK in your Nest.js application using one of these methods:
Synchronous Configuration
Configure the SDK synchronously with forRoot
:
Asynchronous Configuration
Configure the SDK asynchronously with forRootAsync
, ideal for dynamic configuration with ConfigService
:
Wait for Readiness
The SDK initializes automatically during module setup—no need to manually wait for readiness with the injected FsClient
.
User Context Decorator
Simplify user context access by creating a custom decorator that returns an FsUserContext
object. Pass this object to flag()
and track()
functions.
This enables passing @UserContext()
as a parameter in controller methods.
Refer to the Nest.js documentation for Authentication to learn about AuthGuards
, which can append user
incoming requests.
Ensure the key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.
Usage
Evaluate Flags
Evaluate flags with flag()
, which applies targeting rules, rollouts, and defaults for the user context.
An Impression is automatically registered when flag()
is called.
Track Events
Submit user actions with the track
function:
See Events: Tracking to learn about numeric and property events.
SDK Event Listeners
The SDK emits these events for SDK lifecycle management:
SDK_UPDATE
: Emitted when flags are updatedSDK_READY
: Emitted when the SDK is readyERROR
: Emitted when an error occurs during initialization
SDK_UPDATE
does not fire if syncing is disabled.
Configuration
Configure the SDK with the FsConfig
interface:
Custom Attributes
- Define user attributes for targeting in Flags: User Segments.
- See User Context Decorator for the recommended approach to building the context.
Ensure the key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.
Flag Syncing
Configure flag update strategies with the sync
object: stream
, poll
, or off
.
By default, flag updates propagate in milliseconds via server-side events (SSE), ensuring the latest values are used in evaluations.
Stream (Default)
Stream updates via SSE—flag updates are reevaluated on the server and sent to the client:
Polling
Poll the server on an interval:
Off
Disable syncing:
Bootstrapping
Initialize the SDK with a set of bootstrap flags:
Best Practices
- Select a sync strategy (
stream
/poll
/off
) based on your application’s needs. - Create a User Context Decorator for simplified context management.
- Add user attributes for targeted feature rollouts.
Environment Variables
Set the following environment variable:
FLAGSYNC_SDK_KEY
: Your server-side FlagSync SDK key (required)