Nest.js SDK

Overview

The @flagsync/nest-sdk integrates into Nest.js applications for server-side feature management and event tracking—ideal for backend services and APIs.

npm

Latest version available on npm

GitHub

Explore the source code on GitHub

Installation

Install the SDK with your preferred package manager:

npm install @flagsync/nestjs-sdk
npm install -D @flagsync/cli

yarn add @flagsync/nestjs-sdk
yarn add -D @flagsync/cli

pnpm add @flagsync/nestjs-sdk
pnpm add -D @flagsync/cli

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:

app.module.ts

import { Module } from '@nestjs/common';
import { FlagSyncModule } from '@flagsync/nestjs-sdk';

@Module({
  imports: [
    FlagSyncModule.forRoot({
      sdkKey: 'your-sdk-key',
      // other configuration options
    }),
  ],
})
export class AppModule {}

Inject the Client

Use @InjectFlagSync() to inject the client into a Provider (e.g., service, controller, etc.):

app.controller.ts

import { Controller, Get } from '@nestjs/common';
import { FsClient, InjectFlagSync } from '@flagsync/nestjs-sdk';
import { UserContext } from '@app/context.decorator';

@Controller()
export class AppController {
  constructor(@InjectFlagSync() private client: FsClient) {}

  @Get()
  async getMyFlag(@UserContext() context) {
    return this.client.flag(context, 'my-first-kill-switch');
  }
}

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:

import { Module } from '@nestjs/common';
import { FlagSyncModule } from '@flagsync/nestjs-sdk';

@Module({
  imports: [
    FlagSyncModule.forRoot({
      sdkKey: 'your-sdk-key',
    }),
  ],
  ...
})
export class AppModule {}

Asynchronous Configuration

Configure the SDK asynchronously with forRootAsync, ideal for dynamic configuration with ConfigService:

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { FlagSyncModule } from '@flagsync/nestjs-sdk';

@Module({
  imports: [
    ConfigModule.forRoot({
      cache: true,
      isGlobal: true,
    }),
    FlagSyncModule.forRootAsync({
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => {
        return {
          sdkKey: configService.get('FLAGSYNC_SDK_KEY'),
        };
      },
    }),
  ],
  ...
})
export class AppModule {}

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 decorator 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.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { FsUserContext } from '@flagsync/nestjs-sdk';

export const UserContext = createParamDecorator(
  (_, ctx: ExecutionContext): FsUserContext => {
    const request = ctx.switchToHttp().getRequest();

    // Populated via middleware or an AuthGuard
    // Or use request.cookies, etc.
    const user = request.user;

    return {
      key: user.userId,
      attributes: {
        jobTitle: user.role,
        region: request.headers['x-region'] ?? 'Unknown',
      },
    };
  },
);

import { Controller, Get } from '@nestjs/common';
import { FsClient, InjectFlagSync } from '@flagsync/nestjs-sdk';
import { UserContext } from '@app/context.decorator';

@Controller()
export class AppController {
  constructor(@InjectFlagSync() private client: FsClient) {}

  @Get()
  async getMyFlag(@UserContext() context) {
    return this.client.flag(context, 'my-first-kill-switch');
  }
}

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

Evaluates a feature flag for a given user context. Applies targeting rules, rollouts, and defaults values.

client.flag<T>(ctx: FsUserContext, flagKey: string, defaultValue?: T): T

app.service.ts

import { Injectable } from '@nestjs/common';
import { InjectFlagSync, FsClient, FsUserContext } from '@flagsync/nestjs-sdk';

@Injectable()
export class AppService {
  constructor(@InjectFlagSync() private readonly client: FsClient) {}

  // ctx passed from the controller
  async doWork(ctx: FsUserContext) {
    const isEnabled = this.client.flag(ctx, 'feature-enabled', false);
    if (isEnabled) {
      // Feature is enabled
    }
  }
}

FlagSync CLI

When using the CLI, flag values are automatically inferred from the generated types:

client.flag(ctx, 'layout');              // Type: 'v1' | 'v2' | 'v3'
client.flag(ctx, 'killswitch');          // Type: boolean
client.flag(ctx, 'price-discount');      // Type: 0.1 | 0.2
client.flag(ctx, 'price-discount', 0.5); // ❌ TS Error: Invalid default value
client.flag(ctx, 'invalid-flag');        // ❌ TS Error: Invalid flag key

Without generated types, you must manually specify the type:

client.flag<'v1' | 'v2'>(ctx, 'layout');            // Type: 'v1' | 'v2'
client.flag<number>(ctx, 'price-discount');         // Type: number
client.flag<boolean>(ctx, 'enable-feature', false); // Type: boolean (defaultValue must be true or false)
client.flag(ctx, 'no-type')                         // Type: unknown

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.

checkout.service.ts

import { Injectable } from '@nestjs/common';
import { InjectFlagSync, FsClient, FsUserContext } from '@flagsync/nestjs-sdk';
import { PurchaseRequest } from '@app/types';

@Injectable()
export class CheckoutService {
  constructor(
    @InjectFlagSync()
    private readonly client: FsClient,
  ) {}

  async handlePurchase(request: PurchaseRequest, context: FsUserContext) {
    // Property event
    this.client.track(context, 'purchase-request', null, request);

    // Time the operation
    const t0 = Date.now();
    const order = await this.makePurchase(request);
    const receipt = await this.sendOrder(order)
    const t1 = Date.now()

    // Numeric event
    this.client.track(context, 'purchase-duration', t1 - t0);
  }
}

SDK Event Listeners

The SDK emits these events for SDK lifecycle management:

SDK_UPDATE: Emitted when flags are updated
SDK_READY: Emitted when the SDK is ready
ERROR: Emitted when an error occurs during initialization

import { FsEvent } from '@flagsync/js-sdk';

// Flag updates
this.client.on(FsEvent.SDK_UPDATE, () => {
  this.logger.log(`Flags updated at ${new Date().toISOString()}`)
});

SDK_UPDATE does not fire if syncing is disabled.

Configuration

Configure the SDK with the FsConfig interface:

export interface FsConfig {
  sdkKey: string;
  sync?: {
    type?: 'ws' | 'sse' | 'poll' | 'off'; // Optional: Sync strategy (default: 'ws')
    pollRateInSec?: number;               // Optional: Polling interval in seconds
  };
  tracking?: {
    impressions?: {
      maxQueueSize: number;           // Required: Max impressions queue size
      pushRateInSec: number;          // Required: Impressions push rate (seconds)
    };
    events?: {
      maxQueueSize: number;           // Required: Max events queue size
      pushRateInSec: number;          // Required: Events push rate (seconds)
    };
  };
  urls?: {
    ws?: string;                      // Optional: WebSocket sync URL
    sse?: string;                     // Optional: SSE sync URL
    flags?: string;                   // Optional: Flag fetch URL
    events?: string;                  // Optional: Events & impressions URL
  };
  logger?: Partial<ILogger>;          // Optional: Custom logger
  logLevel?: LogLevel;                // Optional: Logging level
  metadata?: Record<string, any>;     // Optional: Additional metadata
}

Custom Attributes

Define user attributes for targeting in Flags: User Segments.
See User Context Decorator for the recommended approach to building the context.

const context: FsUserContext = {
  key: 'user-123',
  attributes: {
    plan: 'premium',
    country: 'US',
    userType: 'enterprise'
  }
}

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: ws, sse, poll, or off.

By default, flag updates propagate in milliseconds over a WebSocket connection, ensuring the latest values are used in evaluations.

WebSocket (Default)

Stream updates over a WebSocket connection—flag updates are reevaluated on the server and pushed to the client in real time:

FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'ws' // Default
  }
});

SSE

Stream updates via server-sent events (SSE):

FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'sse'
  }
});

Polling

Poll the server on an interval:

FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'poll',
    pollRateInSec: 60
  }
});

Off

Disable syncing:

FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'off'
  }
});

Bootstrapping

Initialize the SDK with a set of bootstrap flags:

FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  bootstrap: {
    'my-feature': true,
    'other-feature': false,
  },
});

Best Practices

Select a sync strategy (ws/sse/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)

Getting Started

CLI

Client-Side

Server-Side

Overview

npm

GitHub

Installation

Quickstart

Initialization

Get Your SDK Key

Initialize the SDK

Synchronous Configuration

Asynchronous Configuration

Wait for Readiness

User Context Decorator

Usage

Evaluate Flags

FlagSync CLI

Track Events

SDK Event Listeners

Configuration

Custom Attributes

Flag Syncing

Bootstrapping

Best Practices

Environment Variables

​Overview

npm

GitHub

​Installation

​Quickstart

​Initialization

​Get Your SDK Key

​Initialize the SDK

​Synchronous Configuration

​Asynchronous Configuration

​Wait for Readiness

​User Context Decorator

​Usage

​Evaluate Flags

​FlagSync CLI

​Track Events

​SDK Event Listeners

​Configuration

​Custom Attributes

​Flag Syncing

​Bootstrapping

​Best Practices

​Environment Variables

Overview

Installation

Quickstart

Initialization

Get Your SDK Key

Initialize the SDK

Synchronous Configuration

Asynchronous Configuration

Wait for Readiness

User Context Decorator

Usage

Evaluate Flags

FlagSync CLI

Track Events

SDK Event Listeners

Configuration

Custom Attributes

Flag Syncing

Bootstrapping

Best Practices

Environment Variables