@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
`

$3

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
}
`

$3

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

Usage

$3

#### 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;
};
`

$3

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