ngx-circuit

A powerful, type-safe feature flag library for Angular applications. ngx-circuit allows you to manage feature toggles with ease, supporting various strategies like boolean flags, time-based activation, percentage rollouts, user groups, environment contexts, and more.

Features

• Flexible Configuration: Load flags from a static object or an HTTP endpoint.
• Advanced Flag Types: Support for Boolean, Time-based, Percentage, Group, Environment, Device, and Composite flags.
• Type-Safe: Built with TypeScript for excellent developer experience.
• Structural Directive: Conditionally render templates using *cktCircuit.
• Route Guard: Protect routes using circuitGuard.
• Reactive Service: CircuitService uses Signals for reactive state management.
• Context Awareness: Inject user/session context for advanced flag evaluation.

Installation

Install via npm:

npm install ngx-circuit

Configuration

1. Providing Configuration

You can provide the configuration using provideCircuitConfig in your application config. The configuration can be a simple static object (ideal for key-value pairs or demo purposes) or a URL to load the configuration from a JSON file or API endpoint.

Option A: Static Object

import { ApplicationConfig } from '@angular/core';
import { provideCircuitConfig } from 'ngx-circuit';

export const appConfig: ApplicationConfig = {
  providers: [
    provideCircuitConfig({
      featureA: true,
      featureB: false,
    }),
  ],
};

Option B: HTTP endpoint (Remote Configuration)

Load configuration from a remote JSON file or API.

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideRemoteCircuitConfig } from 'ngx-circuit';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideRemoteCircuitConfig('https://api.example.com/flags', {
      apiKey: 'your-api-key', // Optional: value sent in x-api-key header
    }),
  ],
};

2. Providing Context (Optional)

For advanced flags like Percentage, Group, or Device, you need to provide context about the current user/session.

import { ApplicationConfig } from '@angular/core';
import { provideCircuitConfig, provideCircuitContext } from 'ngx-circuit';

export const appConfig: ApplicationConfig = {
  providers: [
    provideCircuitConfig({ ... }),
    provideCircuitContext({
      userId: 'user-123',
      sessionId: 'session-abc',
      groups: ['beta-testers', 'admin'],
      environment: 'production',
      platform: 'mobile'
    })
    // Or providing a factory function:
    // provideCircuitContext(() => ({ userId: localStorage.getItem('userId') }))
  ],
};

Usage

1. CircuitService

Inject CircuitService to check feature flags programmatically.

import { Component, inject } from '@angular/core';
import { CircuitService } from 'ngx-circuit';

@Component({ ... })
export class MyComponent {
  private circuit = inject(CircuitService);

  checkFeature() {
    if (this.circuit.isEnabled('newFeature')) {
      // feature logic
    }
  }
}

2. Structural Directive (*cktCircuit)

Conditionally render elements in your template.

<div *cktCircuit="'featureA'">Feature A is enabled!</div>

<div *cktCircuit="'featureB'; else fallback">Feature B is enabled!</div>

<ng-template #fallback> Feature B is disabled. </ng-template>

3. Route Guard (circuitGuard)

Protect routes based on feature flags.

import { Routes } from '@angular/router';
import { circuitGuard } from 'ngx-circuit';

export const routes: Routes = [
  {
    path: 'new-feature',
    canActivate: [circuitGuard],
    data: {
      circuit: 'featureA', // Feature flag to check
      circuitRedirectUrl: '/home', // Optional redirect if disabled
    },
    loadComponent: () => import('./...').then((m) => m.NewFeatureComponent),
  },
];

Advanced Usage

1. URL Overrides

You can override feature flags via URL query parameters for testing/QA. This must be explicitly enabled.

providers: [provideCircuitConfig(config, { enableUrlOverrides: true })];

Then append ?circuit=flagName:true,otherFlag:false to your URL.

2. Analytics Integration

Track when feature flags are evaluated to support A/B testing analytics.

1. Implement CircuitTracker:

@Injectable()
export class MyAnalyticsTracker implements CircuitTracker {
  track(feature: string, enabled: boolean): void {
    console.log(`Feature ${feature} evaluated to ${enabled}`);
    // Send to Google Analytics, Mixpanel, etc.
  }
}

2. Provide it in your app config:

providers: [provideCircuitTracker(MyAnalyticsTracker)];

Advanced Flag Types

Define complex rules in your configuration object.

import { CircuitType } from 'ngx-circuit';

const config = {
  // Simple Boolean
  basicFlag: true,

  // Time-based: specific date range
  promoFeature: {
    type: CircuitType.TimeBased,
    startDate: '2023-12-01',
    endDate: '2023-12-31',
  },

  // Percentage Rollout: 20% of users
  betaTest: {
    type: CircuitType.Percentage,
    percentage: 20,
  },

  // User Group
  adminOnly: {
    type: CircuitType.Group,
    groups: ['admin'],
  },

  // Environment Specific
  devTools: {
    type: CircuitType.Environment,
    environments: ['development', 'staging'],
  },

  // Device Specific
  mobileView: {
    type: CircuitType.Device,
    devices: ['mobile', 'tablet'],
  },

  // Composite: ALL conditions must be met
  complexFeature: {
    type: CircuitType.Composite,
    conditions: [
      { type: CircuitType.Group, groups: ['beta-testers'] },
      { type: CircuitType.TimeBased, startDate: '2024-01-01' },
    ],
  },
};

Management Dashboard

This repository also includes a full-stack Circuit Breaker Management Dashboard that you can self-host to manage your feature flags, environments, and projects.

The dashboard consists of:

• Frontend: An Angular application for managing flags.
• Backend API: A NestJS application for storing flag configurations.

For detailed instructions on how to run, build, and deploy the management dashboard, please refer to the GitHub README.

License

MIT