@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

# 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:

{
  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

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

// 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

// 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

// 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:

# 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:

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:

pnpm build

4. Use the new feature flag in your code:

// 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

# Install dependencies
pnpm install

# Build the package
pnpm build