3.8 KiB
Feature Flags
Features inside the woocommerce-admin repository can be in various states of completeness. In addition to the development copy of woocommerce-admin, feature plugin versions are bundled, and code is merged to WooCommerce core. To provide a way for improved control over how these features are released in these different environments, woocommerce-admin has a system for feature flags.
We currently support the following environments:
| Environment | Description |
|---|---|
| development | Development - All features should be enabled in development. These flags are also used in both JS and PHP tests. Ran using npm start. |
| plugin | Plugin - A packaged release of the featured plugin, for GitHub WordPress.org. Ran using npm run-script build:release. |
| core | Core - assets/files ready and stable enough for core merge. Ran using npm pack. (@todo update this with publish command). |
Adding a new flag
Flags can be added to the files located in the config/ directory. Make sure to add a flag for each environment and explicitly set the flag to false.
Please add new feature flags alphabetically so they are easy to find.
Building custom plugin builds
Sometimes it is useful to create a test zip of a plugin, separate from the released WordPress.org version. This makes internal testing easier for non developers, removing the requirment of using Git and NPM commands. These releases are usually uploaded to GitHub releases as a pre release.
You can use the build:release command with the --slug and --features arguments to create a custom build. Base feature flags will be pulled from config/plugin.json and your additional changes are overlaid on top. When the build is complete, a woocommerce-admin-$slug.zip file will be generated.
For example, to create a woocommerce-admin-onboarding.zip build by enabling onboarding in addition to the feature flags defined in config/plugin.json, you would run:
npm run build:release -- --slug onboarding --features '{"onboarding":true}'.
Basic Use - Client
The window.wcAdminFeatures constant is a global variable containing the feature flags.
Instances of window.wcAdminFeatures are replaced during the webpack build process by using webpack's define plugin. Using webpack for this allows us to eliminate dead code when making minified/production builds (plugin, or core environments).
To check if a feature is enabled, you can simplify check the boolean value of a feature:
{ window.wcAdminFeatures[ 'activity-panels' ] && <ActivityPanel /> }
We also expose CSS classes on the body tag, so that you can target specific feature states when they are enabled:
<body class="wp-admin woocommerce-page woocommerce-feature-enabled-activity-panels ....">
Basic Use - Server
Feature flags are also available via PHP. To ensure these are consistent with the built client assets, includes/feature-config.php is generated by the plugin build process or npm start. Do not edit includes/feature-config.php directly.
To check if a feature is enabled, you can use the Automattic\WooCommerce\Admin\Features\Features::is_enabled():
if ( \Automattic\WooCommerce\Admin\Features\Features::is_enabled( 'activity-panels' ) ) {
add_action( 'admin_header', 'wc_admin_activity_panel' );
}
If you name a directory after the flag in includes/ with a class-wc-admin-FEATURE.php file, this code will also automatically be loaded.