Feature Flags

In this chapter, you'll learn what feature flags are, what the available feature flags in MedusaGo are, and how to toggle them.

What are Feature Flags?#

Feature flags allow you to ship new features that are still under development and testing, but not ready for production or wide use yet.

Medusa uses feature flags to ship new versions even when some features are not fully ready. MedusaGo follows the same flags, so the features that are behind a flag in Medusa are behind the same flag in MedusaGo.

Available Feature Flags in MedusaGo#

The following feature flags are available:

Key	Environment Variable	Description
`index_engine`	`MEDUSA_FF_INDEX_ENGINE`	Enables the Admin API's index routes, and lets the routes that list products, and the rule value options of promotions, filter through the Index Module. You must also add the Index Module to your modules.
`translation`	`MEDUSA_FF_TRANSLATION`	Enables the Translation Module, its Admin API routes, and the translation of Store API responses based on the request's locale.
`view_configurations`	`MEDUSA_FF_VIEW_CONFIGURATIONS`	Enables the Admin API routes that manage the Medusa Admin's view configurations and property labels. They respond with a `404` error when the flag is off.
`caching`	`MEDUSA_FF_CACHING`	Lets the framework cache the results of queries through the Caching Module. You must also configure the Caching Module.
`backend_hmr`	`MEDUSA_FF_BACKEND_HMR`	Hot module replacement of the backend in Medusa. It has no effect in MedusaGo, where the `develop` command rebuilds and restarts the server when you change a file.

Toggle Feature Flags#

There are multiple ways to enable or disable feature flags in MedusaGo:

In the medusa-config.go file;
Or using environment variables.

If a flag is set in both, the environment variable wins.

1. Using the `medusa-config.go` file#

The FeatureFlags field of the configuration is a map[string]any to toggle feature flags. Its keys are the feature flags' keys, and its values are booleans indicating whether the feature is enabled.

For example, to enable the translation feature flag in medusa-config.go:

medusa-config.go
return config.InputConfig{
	FeatureFlags: map[string]any{
		"index_engine": true,
		"translation":  true,
	},
}

Make sure to run the migrations after enabling a feature flag, in case it requires database changes:

Terminal

go run . db:migrate

Before disabling a feature flag, make sure to roll back the migrations that depend on it with the db

command.

2. Using Environment Variables#

The feature flags can also be enabled or disabled using environment variables. This is useful to control the feature flag based on the environment.

To toggle a feature flag using an environment variable, set an environment variable with its environment variable name from the table above and set its value to true or false.

For example, to enable the index engine feature flag using an environment variable:

Code

MEDUSA_FF_INDEX_ENGINE=true

Any value other than true (in any letter case) disables the flag.

Make sure to run the migrations after enabling a feature flag, in case it requires database changes.

Enable the Index Engine#

The index engine needs the flag and the Index Module. You enable both in your configuration:

medusa-config.go
return config.InputConfig{
	FeatureFlags: map[string]any{
		"index_engine": true,
	},
	Modules: []config.ModuleConfig{
		{Key: "index", Resolve: "@medusajs/medusa/index-module"},
	},
}

Then, run go run . db:migrate to create the module's tables.

Check Feature Flag Status#

During development, you can check whether a feature flag is enabled. This is useful to add customisations that only apply when a specific feature is enabled.

To build backend customisations around feature flags, use the IsFeatureEnabled function of the feature-flags package of MedusaGo. It accepts a container and a feature flag key, and returns a boolean indicating whether the feature is enabled. You can use it in scripts, subscribers, workflow steps, and API routes (with the request's Scope):

src/scripts/index-engine.go
return featureflags.IsFeatureEnabled(c, featureflags.IndexEngine.Key)

For client customisations, such as admin widgets, send a request to the List Feature Flags API route. It returns the status of every flag in a feature_flags object, and it doesn't require authentication: