import { TypeList } from "docs-ui"

export const metadata = { title: ${pageNumber} Create Custom Feature Flag, }

{metadata.title}

In this chapter, you'll learn how to create a custom feature flag in Medusa.

Why Create a Custom Feature Flag?

As explained in the Feature Flags chapter, feature flags allow the Medusa team to ship new features that are still under development and testing, but not ready for production or wide use yet.

You can also create custom feature flags for your Medusa project or plugin to control the availability of experimental or in-development features. Feature flags allow you to test features in staging, and only enable them in production when they are ready.

How to Create a Custom Feature Flag

1. Define the Feature Flag

To create a custom feature flag, you need to define it in a new file under the src/feature-flags directory of your Medusa project or plugin. The file must export a configuration object.

For example, to define a feature flag that enables a blog feature, create the file src/feature-flags/blog.ts with the following content:

export const featureFlagHighlights = [ ["4", "key", "The unique identifier for the feature flag."], ["5", "default_val", "Whether the feature flag is enabled by default."], ["6", "env_key", "The environment variable key for the feature flag."], ["7", "description", "A brief description of what the feature flag does."] ]

import { FlagSettings } from "@medusajs/framework/feature-flags"

const BlogFeatureFlag: FlagSettings = {
  key: "blog_feature",
  default_val: false,
  env_key: "FF_BLOG_FEATURE",
  description: "Enable blog features",
}

export default BlogFeatureFlag

The feature flag configuration is an object having the following properties:

<TypeList types={[ { type: "string", name: "key", description: "The unique identifier for the feature flag. This key is used to enable or disable the feature flag and check its status.", optional: false }, { type: "boolean", name: "default_val", description: "Whether the feature flag is enabled by default.", optional: false }, { type: "string", name: "env_key", description: "The environment variable key for the feature flag. This key is used to enable or disable the feature flag using environment variables.", optional: false }, { type: "string", name: "description", description: "A brief description of what the feature flag does.", optional: false } ]} />

2. Hide Features Behind the Flag

Next, you can build the features you want to hide behind the feature flag.

To build backend customizations around feature flags, you can either:

• Conditionally run code blocks based on the feature flag status;
• Conditionally load files if the feature flag is not enabled.

For client customizations, such as admin widgets, you can use the Feature Flags API route.

3. Toggle Feature Flag

To enable or disable your custom feature flag, you can either add it to your medusa-config.ts file:

import BlogFeatureFlag from "./src/feature-flags/blog"

module.exports = defineConfig({
  // ...
  featureFlags: {
    [BlogFeatureFlag.key]: true,
  },
})

Or set the environment variable for the feature flag:

FF_BLOG_FEATURE=true

Afterwards, make sure to run migrations if your feature flag requires database changes.

If you're disabling a feature flag, make sure to roll back any migrations that depend on it first.

Write Tests for Features Behind Flags

If you're writing integration tests for features hidden behind feature flags, you can enable the feature flag's environment variable in your integration test using the env option.

For example:

import { medusaIntegrationTestRunner } from "@medusajs/test-utils"

medusaIntegrationTestRunner({
  env: {
    FF_BLOG_FEATURE: true,
  },
  testSuite: ({ api, getContainer }) => {
    // TODO write tests...
  },
})

Then, the Medusa application will load your customizations hidden behind the feature flag as part of the integration tests.