|
| 1 | +--- |
| 2 | +title: Features configuration |
| 3 | +sidebar_label: Features |
| 4 | +description: Enable experimental Strapi features |
| 5 | +displayed_sidebar: devDocsConfigSidebar |
| 6 | +--- |
| 7 | + |
| 8 | +# Features configuration |
| 9 | + |
| 10 | +The `config/features.js|ts` file is used to enable feature flags. Currently this file only includes a `future` object used to enable experimental features through **future flags**. |
| 11 | + |
| 12 | +Some incoming Strapi features are not yet ready to be shipped to all users, but Strapi still offers community users the opportunity to provide early feedback on these new features or changes. With these experimental features, developers have the flexibility to choose and integrate new features and changes into their Strapi applications as they become available in the current major version as well as assist us in shaping these new features. |
| 13 | + |
| 14 | +Such experimental features are indicated by a <FutureBadge /> badge throughout the documentation and enabling these features requires enabling the corresponding future flags. Future flags differ from features that are in alpha in that future flags are disabled by default. |
| 15 | + |
| 16 | +:::danger |
| 17 | +Enable future flags at your own risk. Experimental features may be subject to change or removal, may contain breaking changes, may be unstable or not fully ready for use, and some parts may still be under development or using mock data. |
| 18 | +::: |
| 19 | + |
| 20 | +<!-- ! Commented out as not relevant for now --> |
| 21 | +<!-- Future flags can also be utilized for enabling coming breaking changes in upcoming versions (when prefixed by `vX`, with 'X' being the target version). In this scenario, if you decide to enable a future flag for a breaking change, you will need to migrate your application to adapt to this breaking change. The benefit of this approach however, is that changes can be adopted incrementally as opposed to one large migration when the next major release occurs. Some of these flags may have started out as regular unstable but development showed the need for breaking changes. Finally, the aim of this is to empower developers to be able to smoothly transition to new major versions without the need to modify their existing application code where possible. --> |
| 22 | + |
| 23 | +## Enabling a future flag |
| 24 | + |
| 25 | +To enable a future flag: |
| 26 | + |
| 27 | +1. (_optional_) If the server is running, stop it with `Ctrl-C`. |
| 28 | +2. Open the `config/features.js|ts` file or create it if the file does not exist yet. The file will export a `future` object with all the future flags to enable. |
| 29 | +3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `contentReleases` future flag: |
| 30 | + |
| 31 | + <Tabs groupId='js-ts'> |
| 32 | + |
| 33 | + <Tab value="js" label="JavaScript"> |
| 34 | + |
| 35 | + ```ts title="/config/features.ts" |
| 36 | + module.export = ({ env }) => ({ |
| 37 | + future: { |
| 38 | + // You could also simply write: contentReleases: true |
| 39 | + contentReleases: env.bool('STRAPI_FEATURES_FUTURE_CONTENT_RELEASES', false), |
| 40 | + }, |
| 41 | + }) |
| 42 | + |
| 43 | + ``` |
| 44 | + |
| 45 | + This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line: |
| 46 | + |
| 47 | + ```json title=".env" |
| 48 | + STRAPI_FEATURES_FUTURE_CONTENT_RELEASES=true |
| 49 | + ``` |
| 50 | + |
| 51 | + If your environment file does not include this value, the `contentReleases` future flag property value will default to `false` and the experimental feature will not be enabled. |
| 52 | + |
| 53 | + </Tab> |
| 54 | + |
| 55 | + <Tab value="ts" label="TypeScript"> |
| 56 | + |
| 57 | + ```ts title="/config/features.ts" |
| 58 | + export default { |
| 59 | + future: { |
| 60 | + // You could also simply write: contentReleases: true |
| 61 | + contentReleases: env.bool('STRAPI_FEATURES_FUTURE_CONTENT_RELEASES', false), |
| 62 | + }, |
| 63 | + }; |
| 64 | + ``` |
| 65 | + |
| 66 | + This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line: |
| 67 | + |
| 68 | + ```json title=".env" |
| 69 | + STRAPI_FEATURES_FUTURE_CONTENT_RELEASES=true |
| 70 | + ``` |
| 71 | + |
| 72 | + If your environment file does not include this value, the `contentReleases` future flag property value will default to `false` and the experimental feature will not be enabled. |
| 73 | + |
| 74 | + </Tab> |
| 75 | + </Tabs> |
| 76 | + |
| 77 | +4. Rebuild the admin panel and restart the server: |
| 78 | + |
| 79 | + <Tabs groupId="yarn-npm"> |
| 80 | + <Tab value="yarn" label="Yarn"> |
| 81 | + |
| 82 | + ```sh |
| 83 | + yarn develop |
| 84 | + ``` |
| 85 | + </Tab> |
| 86 | + <Tab value="npm" label="NPM"> |
| 87 | + |
| 88 | + ```sh |
| 89 | + npm run develop |
| 90 | + ``` |
| 91 | + |
| 92 | + </Tab> |
| 93 | + </Tabs> |
| 94 | + |
| 95 | +## Future flags API |
| 96 | + |
| 97 | +Developers can use the following APIs to interact with future flags: |
| 98 | + |
| 99 | +- Features configuration is part of the `config` object and can be read with `strapi.config.get('features')` or with `strapi.features.config`. |
| 100 | + |
| 101 | +- `strapi.features.future` returns the `isEnabled()` that can be used to determine if a future flag is enabled, using the following method: `strapi.features.future.isEnabled('featureName')`. |
| 102 | + |
| 103 | +## Available future flags |
| 104 | + |
| 105 | +The following future flags are currently available and can be used in the `future` object of the `config/features` configuration file: |
| 106 | + |
| 107 | +| Property name | Related feature | Suggested environment variable name | |
| 108 | +| ----------------- | -------------------------------------------- | ----------------------------------------- | |
| 109 | +| `contentReleases` | [Releases](/user-docs/releases/introduction) | `STRAPI_FEATURES_FUTURE_CONTENT_RELEASES` | |
0 commit comments