> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flagsync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nest.js SDK

> Integrate FlagSync feature flags into Nest.js applications.

## Overview

The `@flagsync/nest-sdk` integrates into [Nest.js](https://nestjs.com/) applications for server-side feature management and event tracking—ideal for backend services and APIs.

> [card] [npm](https://www.npmjs.com/package/@flagsync/nestjs-sdk)
>
> Latest version available on npm

> [card] [GitHub](https://github.com/flagsync/nestjs-sdk/)
>
> Explore the source code on GitHub

## Installation

Install the SDK with your preferred package manager:

```bash npm theme={null}
npm install @flagsync/nestjs-sdk
npm install -D @flagsync/cli
```

```bash yarn theme={null}
yarn add @flagsync/nestjs-sdk
yarn add -D @flagsync/cli
```

```bash pnpm theme={null}
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:

**1. Configure the Module**

Import `FlagSyncModule` in your `app.module.ts`:

```typescript app.module.ts theme={null}
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 {}
```

**2. Inject the Client**

Use `@InjectFlagSync()` to inject the client into a [Provider](https://docs.nestjs.com/providers) (e.g., service, controller, etc.):

```typescript app.controller.ts theme={null}
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

> [!WARNING]
>
> 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](https://docs.nestjs.com/fundamentals/lifecycle-events#application-shutdown)

### Get Your SDK Key

Find your server-side SDK key in your [workspace settings](https://www.flagsync.com/dashboard/settings/organization/workspaces/). 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`:

```typescript theme={null}
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`:

```typescript theme={null}
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](https://docs.nestjs.com/custom-decorators#decorator-composition) that returns an `FsUserContext` object. Pass this object to `flag()` and `track()` functions.

This decorator enables passing `@UserContext()` as a parameter in controller methods.

> [!TIP]
>
> Refer to the Nest.js documentation for [Authentication](https://docs.nestjs.com/security/authentication) to learn about `AuthGuards`, which can append `user` incoming requests.

```typescript @app/context.decorator.ts theme={null}
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',
      },
    };
  },
);
```

```typescript app.controller.ts theme={null}
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');
  }
}
```

> [!WARNING]
>
> Ensure the `key` in `FsUserContext` is unique and persistent for accurate MAU tracking and consistent flag evaluations. See [User Context Best Practices](https://docs.flagsync.com/sdks/overview.md#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.

```typescript theme={null}
client.flag<T>(ctx: FsUserContext, flagKey: string, defaultValue?: T): T
```

```typescript app.service.ts {10} theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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
```

> [!TIP]
>
> An [Impression](https://docs.flagsync.com/impressions/generating.md) is automatically registered when `flag()` is called.

### Track Events

Submit user actions with the `track` function:

> [!TIP]
>
> See [Events: Tracking](https://docs.flagsync.com/events/tracking.md) to learn about numeric and property events.

```typescript checkout.service.ts {14, 23} theme={null}
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

```typescript theme={null}
import { FsEvent } from '@flagsync/js-sdk';

// Flag updates
this.client.on(FsEvent.SDK_UPDATE, () => {
  this.logger.log(`Flags updated at ${new Date().toISOString()}`)
});
```

> [!NOTE]
>
> `SDK_UPDATE` does not fire if syncing is disabled.

## Configuration

Configure the SDK with the `FsConfig` interface:

```typescript theme={null}
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](https://docs.flagsync.com/flags/targeting-and-rollouts.md#user-segments).
* See [User Context Decorator](#user-context-decorator) for the recommended approach to building the context.

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

> [!WARNING]
>
> Ensure the `key` in `FsUserContext` is unique and persistent for accurate MAU tracking and consistent flag evaluations. See [User Context Best Practices](https://docs.flagsync.com/sdks/overview.md#user-context-best-practices) for details.

### Flag Syncing

Configure flag update strategies with the `sync` object: `ws`, `sse`, `poll`, or `off`.

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

**1. WebSocket (Default)**

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

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

**2. SSE**

Stream updates via server-sent events (SSE):

```typescript theme={null}
FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'sse'
  }
});
```

**3. Polling**

Poll the server on an interval:

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

**4. Off**

Disable syncing:

```typescript theme={null}
FlagSyncModule.forRoot({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'off'
  }
});
```

### Bootstrapping

Initialize the SDK with a set of bootstrap flags:

```typescript theme={null}
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](#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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.