NestJS Unleash Client

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.