Feature Flags

Adding a Feature Flag

1. Add to enum in commons-packages/shared/graphql/enums/feature-flags.enum.ts:

   typescriptCopy

   export enum FeatureFlags {
     // ... existing flags (alphabetically sorted)
     myNewFeatureFlag = 'myNewFeatureFlag',
   }
   

2. Create migration using npm run migrate:make add-feature-flag-my-new-feature:

   typescriptCopy

   import type { Knex } from 'knex';
   import {
     createFeatureFlagWithDescriptionAndTeam,
     rollbackCreateFeatureFlag,
   } from '@commons/backend/models/migrations/helpers/feature-flag-helpers';
   
   const FEATURE_FLAG_NAME = 'myNewFeatureFlag'; // Use string literal, NOT enum
   
   export async function up(knex: Knex): Promise<number[]> {
     return createFeatureFlagWithDescriptionAndTeam(
       FEATURE_FLAG_NAME,
       knex,
       'Brief description of what this flag controls',
       'Team Name', // e.g., 'Care Delivery', 'Platform', 'Growth'
     );
   }
   
   export async function down(knex: Knex): Promise<number> {
     return rollbackCreateFeatureFlag(FEATURE_FLAG_NAME, knex);
   }
   

3. Ask user for team name to associate with the flag.

Removing a Feature Flag

1. Create migration using npm run migrate:make remove-feature-flag-my-feature:

   typescriptCopy

   import type { Knex } from 'knex';
   import {
     markFeatureFlagDeleted,
     rollbackMarkFeatureFlagDeleted,
   } from '@commons/backend/models/migrations/helpers/feature-flag-helpers';
   
   const FEATURE_FLAG_NAME = 'myFeatureFlag'; // Use string literal, NOT enum
   
   export async function up(knex: Knex): Promise<any> {
     await markFeatureFlagDeleted(FEATURE_FLAG_NAME, knex);
   }
   
   export async function down(knex: Knex): Promise<any> {
     await rollbackMarkFeatureFlagDeleted(FEATURE_FLAG_NAME, knex);
   }
   

2. Remove from enum in commons-packages/shared/graphql/enums/feature-flags.enum.ts

Naming Conventions

• camelCase for flag names (e.g., carePlanImprovements, gcAiTextAgent)
• Descriptive and specific to the feature
• Avoid generic names like newFeature or enableThing

Important

• In migrations, always use string literals, not enum values—the enum may change before the migration runs in all environments.
• Flags are disabled by default; they must be enabled per-market in the database.
• Template files: commons-packages/backend/models/migrations/examples/_feature-flag-*.ts