npm package: @formio/feature-flags
Description: Feature flag management for Form.io applications
Author: Form.io
Latest version: 1.1.0

# @formio/feature-flags

A flag management system for Form.io applications that works in both backend and frontend  environments.

## Overview

Environment-based feature flag system that allows you to:
- Toggle features on/off using environment variables
- Share feature flag configuration between frontend and backend
- Centralize feature flag definitions in one place

## Installation

```bash
# In the monorepo
pnpm add @formio/feature-flags
```

### Feature Flag Registry

All feature flags are defined in a central registry (`FEATURE_FLAGS`) with the following properties:

```typescript
{
  key: string;           // The flag identifier (e.g., 'FEATUREX')
  defaultValue: boolean; // Default value when no environment variable is set
  envVar: string;        // Environment variable name (e.g., 'FORMIO_FEATURE_FEATUREX')
  description?: string;  // Optional description of the feature
}
```

### Current Feature Flags

- **ESIGNATURE**: Enable/disable eSignature features
  - Environment Variable: `FORMIO_FEATURE_ESIGNATURE`
  - Default: `false`

## Usage

### Backend

#### In Configuration Files

```typescript
const featureFlags = require('@formio/feature-flags');

// Helper to get config from environment or docker secrets
const getConfig = (key, defaultValue) => {
  if (process.env.hasOwnProperty(key)) {
    return process.env[key];
  }
  return defaultValue;
};

// Get all feature flags with resolved values
const flags = featureFlags.getFeatureFlags(getConfig);
console.log(flags.ESIGNATURE); // true or false

// Check a specific flag
const isEnabled = featureFlags.isFeatureEnabled(
  featureFlags.FEATURE_FLAGS.ESIGNATURE.key, 
  getConfig
);
```

#### In Server/App Configuration

```javascript
// apps/formio-server/config.js
const featureFlags = require('@formio/feature-flags');

module.exports = function() {
  const config = {};
  
  // Export the FEATURE_FLAGS constant for structured access
  config.FEATURE_FLAGS = featureFlags.FEATURE_FLAGS;
  
  // Get all feature flags with config overrides
  config.featureFlags = featureFlags.getFeatureFlags(getConfig);
  
  // Helper function to check if a feature flag is enabled
  config.isFeatureEnabled = (flagKey) => {
    return featureFlags.isFeatureEnabled(flagKey, getConfig);
  };
  
  return config;
};
```

### Frontend

#### In Portal Formio Provider

```javascript
// apps/formio-app/src/scripts/app.js
import { isFeatureEnabled, FEATURE_FLAGS } from '@formio/feature-flags';

angular
  .provider('FeatureFlags', function() {
    let featureFlags = {};

    this.setfeatureFlagsConfig = function(config) {
      featureFlags = config;
    };

    this.$get = function() {
      return function(flag) {
        const getConfig = function() {
          if (flag) {
            return featureFlags?.[flag.key] || flag.defaultValue;
          }
        };
        return isFeatureEnabled(flag, getConfig);
      };
    };
  })
  .config([
    ...
    'FeatureFlagsProvider',
    function(
    ...
    FeatureFlagsProvider
  ) {
    ...
    FeatureFlagsProvider.setfeatureFlagsConfig(AppConfig.featureFlags);
    ...
    // Check if eSignature is enabled
    if (FeatureFlagsProvider.$get()(FEATURE_FLAGS.ESIGNATURE)) {
      // Enable eSignature features
    }
  }])
```

#### In Controllers/Components

```javascript
// Check if eSignature is enabled using the frontend service
if (FeatureFlags(FEATURE_FLAGS.ESIGNATURE)) {
  // Show eSignature UI
}
```


## Environment Configuration

Feature flags can be controlled via environment variables:

```bash
# Or in .env file
FORMIO_FEATURE_ESIGNATURE=true
```

## Adding New Feature Flags

To add a new feature flag:

1. Open `packages/feature-flags/src/types.ts`
2. Add your feature flag to the `FEATURE_FLAGS` registry:

```typescript
export const FEATURE_FLAGS = {
  ESIGNATURE: {
    key: 'ESIGNATURE',
    defaultValue: false,
    envVar: 'FORMIO_FEATURE_ESIGNATURE',
    description: 'Enable eSignature features'
  },
  MY_NEW_FEATURE: {
    key: 'MY_NEW_FEATURE',
    defaultValue: false,
    envVar: 'FORMIO_FEATURE_MY_NEW_FEATURE',
    description: 'Description of my new feature'
  }
} as const;
```

3. Rebuild the package:

```bash
pnpm build
```

4. Use the new feature flag in your code:

```javascript
// Backend
if (config.isFeatureEnabled(config.FEATURE_FLAGS.MY_NEW_FEATURE.key)) {
  // Feature code
}

// Frontend
if (FeatureFlagsChecker.isEnabled(FEATURE_FLAGS.MY_NEW_FEATURE.key)) {
  // Feature UI
}
```

## Development

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build
```