NestJS Unleash Client

A NestJS module for Unleash, providing feature flagging with a global Guard and decorators.

Table of Contents

• Installation
• Usage
  • Import the Module
  • Parameter Options
  • Protecting a Route with a Feature Toggle
  • Injecting the Unleash Client
• Resources
• Stay in touch
• License

⚠️ Important: Starting from this version, the minimum required Node.js version is 20.

Installation

$ npm i @alpha018/nestjs-unleash-client

Usage

Import The Module

To use the Unleash client in your application, import the module into your main module. The module registers a global guard that will automatically protect routes decorated with @UnleashToggle.

Static Registration

import { UnleashClientModule } from '@alpha018/nestjs-unleash-client';

@Module({
  imports: [
    // ...
    UnleashClientModule.forRoot({
      config: {
        url: 'http://unleash.herokuapp.com/api/',
        appName: 'my-nestjs-app',
      },
      isGlobal: true, // Make the module and its providers global
    }),
    // ...
  ],
})
export class AppModule {}

Async Registration

import { UnleashClientModule } from '@alpha018/nestjs-unleash-client';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    // ...
    UnleashClientModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        config: {
          url: configService.get('UNLEASH_URL'),
          appName: configService.get('UNLEASH_APP_NAME'),
          customHeaders: { Authorization: configService.get('UNLEASH_API_TOKEN') },
        }
      }),
      inject: [ConfigService],
      isGlobal: true, // Make the module and its providers global
    }),
    // ...
  ],
})
export class AppModule {}

Parameter Options

Options for forRoot and forRootAsync:

Parameter	Type	Required	Description
config	UnleashConfig	Yes	The configuration object for the unleash-client. See options below.
isGlobal	boolean	No	If true, the module will be registered as a global module. Defaults to false.

The config object is passed directly to the unleash-client. The most common options are:

config Parameter	Type	Required	Description
url	string	Yes	The URL of your Unleash server API.
appName	string	Yes	The name of your application.
customHeaders	object	No	Custom headers to be sent to the Unleash API. Use Authorization for the API key generated by the Unleash panel.
...	any	No	Any other valid option from the official unleash-client-node documentation.

Protecting a Route with a Feature Toggle

To protect an endpoint with a feature toggle, use the @UnleashToggle decorator. The global UnleashGuard will automatically deny access if the feature is disabled.

import { Controller, Get } from '@nestjs/common';
import { UnleashToggle } from '@alpha018/nestjs-unleash-client';

@Controller()
export class AppController {
  @Get('hello')
  @UnleashToggle('my-feature-toggle')
  getHello(): string {
    // This route is only accessible if 'my-feature-toggle' is enabled in Unleash
    return 'Hello World!';
  }

  @Get('unprotected')
  getUnprotectedHello(): string {
    // This route is always accessible as it does not have the @UnleashToggle decorator
    return 'This is an unprotected route.';
  }
}

Injecting the Unleash Client

If you need to check a feature toggle directly in your code, you can inject the UnleashClientProvider.

import { Controller, Get } from '@nestjs/common';
import { UnleashClientProvider } from '@alpha018/nestjs-unleash-client';

@Controller()
export class AppController {
  constructor(private readonly unleashProvider: UnleashClientProvider) {}

  @Get('check')
  checkFeature() {
    if (this.unleashProvider.isEnabled('my-other-feature')) {
      // Logic for when the feature is enabled
      return 'Feature is enabled!';
    } else {
      // Logic for when the feature is disabled
      return 'Feature is disabled!';
    }
  }
}

Resources

Check out a few resources that may come in handy when working with NestJS:

• Visit the NestJS Documentation to learn more about the framework.
• Visualize your application graph and interact with the NestJS application in real-time using NestJS Devtools.

Stay in touch

• Author - Tomás Alegre

License

This project is MIT licensed.