Skip to content

Reland "Add feature flags to the framework" #171545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
auto-submit merged 2 commits into from
Jul 15, 2025
Merged

Reland "Add feature flags to the framework" #171545

auto-submit merged 2 commits into from
Jul 15, 2025

Conversation

@loic-sharma
Copy link
Member

@loic-sharma loic-sharma commented Jul 2, 2025 •
edited
Loading

This relands #168437. The google3 fixes were landed in: #171547, https://critique.corp.google.com/cl/781275353, #171933.

This PR is split into two commits:

  1. d625379, code from Add feature flags to the framework #168437 without any changes
  2. f35d29e, updates the PR to omit obvious types.

Original PR description:

Motivation

We'd like to let users opt-in to experimental features so that they can give early feedback while we iterate on the feature. For example:

Example feature flags:

  1. Android sensitive content: [Android] Implement setting content sensitivity on Android #158473. When enabled, Flutter will tell Android when the view contains sensitive content like a password.
  2. Desktop multi-window. When enabled, Flutter will use child windows to allow things like a context menu to "escape" outside of the current window.

Use case

Users will be able to turn on features by:

  • Option 1: Run flutter config --enable-my-feature. This enables the feature for all projects on the machine
  • Option 2: Add enable-my-feature: true in their pubspec.yaml, under the flutter section. This would enable the for a single project on the machine.

Turning on a feature affects both development-time (flutter run) and deployment-time (flutter build x). For example, I can flutter build windows to create an .exe with multi-window features enabled.

How this works

This adds a new runtimeId property to the tool's Feature class. If a feature is on and has a runtimeId, its runtimeId will be stamped into the Dart application as a Dart define. The framework uses this Dart define to determine which features are enabled.

Multi-window example

#168697 shows how this new feature flag system can be used to add a multi-window feature flag:

  1. It adds a new multi-window feature to the Flutter tool. This can be turned on using flutter config --enable-multi-window or by putting enable-multi-window: true in an app's .pubspec, under the flutter section.
  2. It adds a new isMultiWindowEnabled property to the framework.
  3. The Material library can use this new property to determine whether it should create a new window. Example.

Limitations

Tool and framework only

For now, these feature flags are available only to the Flutter tool and Flutter framework. The flags are not automatically available to the embedder or the engine.

For example, embedders need to configure their surfaces differently if Impeller is enabled. This configuration must happen before the Dart isolate is launched. As a result, the framework's feature flags is not a viable solution for this scenario for now. For these kinds of scenarios, we should continue to use platform-specific configuration like the AndroidManifest.xml or Info.plist files.

This is a fixable limitation, we just need to invest in this plumbing :)

Tree shaking

Feature flags are not designed to help tree shaking. For example, you cannot conditionally import Dart code depending on the enabled feature flags. Code that is feature flagged off will still be imported into user's apps.

@github-actions github-actions bot added c: contributor-productivity Team-specific productivity, code health, technical debt. tool Affects the "flutter" command-line tool. See also t: labels. framework flutter/packages/flutter repository. See also f: labels. d: docs/ flutter/flutter/docs, for contributors labels Jul 2, 2025
@ueman ueman mentioned this pull request Jul 3, 2025
Merged
6 tasks
@loic-sharma
Add feature flags to the framework (flutter#168437)
d625379 
## Motivation

We'd like to let users opt-in to experimental features so that they can
give early feedback while we iterate on the feature. For example:

Example feature flags:

1. Android sensitive content:
flutter#158473. When enabled, Flutter
will tell Android when the view contains sensitive content like a
password.
2. Desktop multi-window. When enabled, Flutter will use child windows to
allow things like a context menu to "escape" outside of the current
window.

### Use case

Users will be able to turn on features by:

* **Option 1**: Run `flutter config --enable-my-feature`. This enables
the feature for all projects on the machine
* **Option 2**: Add `enable-my-feature: true` in their `pubspec.yaml`,
under the `flutter` section. This would enable the for a single project
on the machine.

Turning on a feature affects _both_ development-time (`flutter run`) and
deployment-time (`flutter build x`). For example, I can `flutter build
windows` to create an `.exe` with multi-window features enabled.

## How this works

This adds a new
[`runtimeId`](https://github.com/flutter/flutter/pull/168437/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R243-R247)
property to the tool's `Feature` class. If a feature is on and has a
`runtimeId`, its `runtimeId` will be [stamped into the Dart application
as a Dart
define](https://github.com/flutter/flutter/pull/168437/files#diff-bd662448bdc2e6f50e47cd3b20b22b41a828561bce65cb4d54ea4f5011cc604eR293-R327).
The framework uses this Dart define to [determine which features are
enabled](https://github.com/flutter/flutter/pull/168437/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45).

### Multi-window example

flutter#168697 shows how this new
feature flag system can be used to add a multi-window feature flag:

1. It adds a new [multi-window
feature](https://github.com/flutter/flutter/pull/168697/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R189-R198)
to the Flutter tool. This can be turned on using `flutter config
--enable-multi-window` or by putting `enable-multi-window: true` in an
app's .pubspec, under the `flutter` section.
2. It adds a new
[`isMultiWindowEnabled`](https://github.com/flutter/flutter/pull/168697/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45R7-R11)
property to the framework.
3. The Material library can use this new property to determine whether
it should create a new window.
[Example](https://github.com/flutter/flutter/pull/168697/files#diff-2cbc1634ed6b61d61dfa090e7bfbbb7c60b74c8abc3a28df6f79eee691fd1b73).

## Limitations

### Tool and framework only

For now, these feature flags are available only to the Flutter tool and
Flutter framework. The flags are not automatically available to the
embedder or the engine.

For example, embedders need to configure their surfaces differently if
Impeller is enabled. This configuration must happen before the Dart
isolate is launched. As a result, the framework's feature flags is not a
viable solution for this scenario for now. For these kinds of scenarios,
we should continue to use platform-specific configuration like the
`AndroidManifest.xml` or `Info.plist` files.

This is a fixable limitation, we just need to invest in this plumbing :)

### Tree shaking

Feature flags are not designed to help tree shaking. For example, you
cannot conditionally import Dart code depending on the enabled feature
flags. Code that is feature flagged off will still be imported into
user's apps.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
@loic-sharma loic-sharma force-pushed the framework_feature_flags_reland branch from 066b344 to d625379 Compare July 12, 2025 02:00
@loic-sharma loic-sharma force-pushed the framework_feature_flags_reland branch from 5d03f58 to f35d29e Compare July 14, 2025 20:35
@loic-sharma loic-sharma requested a review from bkonyi July 14, 2025 21:31
@loic-sharma loic-sharma marked this pull request as ready for review July 14, 2025 21:31
@loic-sharma loic-sharma requested a review from matanlurey as a code owner July 14, 2025 21:31
@loic-sharma loic-sharma added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 14, 2025
@auto-submit auto-submit bot added this pull request to the merge queue Jul 15, 2025
Merged via the queue into flutter:master with commit 6474b04 Jul 15, 2025
152 checks passed
@flutter-dashboard flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 15, 2025
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Jul 15, 2025
Closed
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 15, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
d4ba6b6 
…r#171545)
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Jul 15, 2025
Merged
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 15, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
60adc9c 
…r#171545)
auto-submit bot pushed a commit to flutter/packages that referenced this pull request Jul 15, 2025
@engine-flutter-autoroll
Roll Flutter from a930ec1a6c09 to cc3110c59022 (24 revisions) (#9631)
2a0b7ef 
flutter/flutter@a930ec1...cc3110c

2025-07-15 [email protected] feat: Tag Fuchsia artifacts by content hash (flutter/flutter#172132)
2025-07-15 [email protected] Marks Linux_android_emu native_assets_android to be unflaky (flutter/flutter#171145)
2025-07-15 [email protected] [ Tool ] Fix `flutter upgrade` stating that an upgrade is available on `main` when up to date (flutter/flutter#172141)
2025-07-15 [email protected] Reland "Add feature flags to the framework" (flutter/flutter#171545)
2025-07-14 [email protected] chore: unskip tests cases (flutter/flutter#172031)
2025-07-14 [email protected] Route transition duration (flutter/flutter#171109)
2025-07-14 [email protected] [Impeller] libImpeller: Correctly release mappings created using the C++ API wrapper. (flutter/flutter#172136)
2025-07-14 [email protected] Roll Skia from 5f7adef2ac25 to 2f4ad5d83704 (3 revisions) (flutter/flutter#172134)
2025-07-14 [email protected] Migrate to arm based firebase test devices for api 26 and 27 (flutter/flutter#172128)
2025-07-14 [email protected] [web] Cleanup unnecessary dart defines and renderer in web tests (flutter/flutter#172130)
2025-07-14 [email protected] Use granular skparagraph targets (flutter/flutter#161676)
2025-07-14 [email protected] [ Widget Preview ] Initial work to support reacting to IDE events (flutter/flutter#172040)
2025-07-14 [email protected] Roll Skia from e95c92d867b5 to 5f7adef2ac25 (8 revisions) (flutter/flutter#172123)
2025-07-14 [email protected] [skia] Set GN flags explicitly for fuchsia build (flutter/flutter#172104)
2025-07-14 [email protected] fix: documentation around led launch broken (flutter/flutter#171983)
2025-07-14 [email protected] [ Tool ] Downgrade and pin DDS to 5.0.3 (flutter/flutter#172120)
2025-07-14 [email protected] Apply superellipse clipping to iOS platform views using an approximated round rect (flutter/flutter#172033)
2025-07-14 [email protected] [Impeller] Fix broken image links in documentation. (flutter/flutter#171465)
2025-07-14 [email protected] remove `x86` in CI  builder linux_android_emulator (flutter/flutter#170964)
2025-07-14 [email protected] remove `x86` in flutter_gdb (flutter/flutter#170966)
2025-07-14 [email protected] fix android studio lint about lambda function (flutter/flutter#172063)
2025-07-14 [email protected] Roll Fuchsia Linux SDK from qw0YTtPhosk3-rr4h... to tQAtsLtpc0oBIqRwC... (flutter/flutter#172116)
2025-07-14 [email protected] Roll Skia from 92354f64e37f to e95c92d867b5 (1 revision) (flutter/flutter#172111)
2025-07-14 [email protected] [web] Delete unused files in the engine (flutter/flutter#172035)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
azatech pushed a commit to azatech/flutter that referenced this pull request Jul 28, 2025
@loic-sharma @azatech
Reland "Add feature flags to the framework" (flutter#171545)
3605778 
This relands flutter#168437. The google3
fixes were landed in: flutter#171547,
https://critique.corp.google.com/cl/781275353,
flutter#171933.

This PR is split into two commits:

1. d625379, code from
flutter#168437 without any changes
2. f35d29e, updates the PR to omit
obvious types.

Original PR description:

## Motivation

We'd like to let users opt-in to experimental features so that they can
give early feedback while we iterate on the feature. For example:

Example feature flags:

1. Android sensitive content:
flutter#158473. When enabled, Flutter
will tell Android when the view contains sensitive content like a
password.
3. Desktop multi-window. When enabled, Flutter will use child windows to
allow things like a context menu to "escape" outside of the current
window.

### Use case

Users will be able to turn on features by:

* **Option 1**: Run `flutter config --enable-my-feature`. This enables
the feature for all projects on the machine
* **Option 2**: Add `enable-my-feature: true` in their `pubspec.yaml`,
under the `flutter` section. This would enable the for a single project
on the machine.

Turning on a feature affects _both_ development-time (`flutter run`) and
deployment-time (`flutter build x`). For example, I can `flutter build
windows` to create an `.exe` with multi-window features enabled.

## How this works

This adds a new
[`runtimeId`](https://github.com/flutter/flutter/pull/168437/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R243-R247)
property to the tool's `Feature` class. If a feature is on and has a
`runtimeId`, its `runtimeId` will be [stamped into the Dart application
as a Dart
define](https://github.com/flutter/flutter/pull/168437/files#diff-bd662448bdc2e6f50e47cd3b20b22b41a828561bce65cb4d54ea4f5011cc604eR293-R327).
The framework uses this Dart define to [determine which features are
enabled](https://github.com/flutter/flutter/pull/168437/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45).

### Multi-window example

flutter#168697 shows how this new
feature flag system can be used to add a multi-window feature flag:

1. It adds a new [multi-window
feature](https://github.com/flutter/flutter/pull/168697/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R189-R198)
to the Flutter tool. This can be turned on using `flutter config
--enable-multi-window` or by putting `enable-multi-window: true` in an
app's .pubspec, under the `flutter` section.
2. It adds a new
[`isMultiWindowEnabled`](https://github.com/flutter/flutter/pull/168697/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45R7-R11)
property to the framework.
4. The Material library can use this new property to determine whether
it should create a new window.
[Example](https://github.com/flutter/flutter/pull/168697/files#diff-2cbc1634ed6b61d61dfa090e7bfbbb7c60b74c8abc3a28df6f79eee691fd1b73).

## Limitations

### Tool and framework only

For now, these feature flags are available only to the Flutter tool and
Flutter framework. The flags are not automatically available to the
embedder or the engine.

For example, embedders need to configure their surfaces differently if
Impeller is enabled. This configuration must happen before the Dart
isolate is launched. As a result, the framework's feature flags is not a
viable solution for this scenario for now. For these kinds of scenarios,
we should continue to use platform-specific configuration like the
`AndroidManifest.xml` or `Info.plist` files.

This is a fixable limitation, we just need to invest in this plumbing :)

### Tree shaking

Feature flags are not designed to help tree shaking. For example, you
cannot conditionally import Dart code depending on the enabled feature
flags. Code that is feature flagged off will still be imported into
user's apps.
vashworth pushed a commit to vashworth/packages that referenced this pull request Jul 30, 2025
@engine-flutter-autoroll @vashworth
Roll Flutter from a930ec1a6c09 to cc3110c59022 (24 revisions) (flutte…
afa5605 
…r#9631)

flutter/flutter@a930ec1...cc3110c

2025-07-15 [email protected] feat: Tag Fuchsia artifacts by content hash (flutter/flutter#172132)
2025-07-15 [email protected] Marks Linux_android_emu native_assets_android to be unflaky (flutter/flutter#171145)
2025-07-15 [email protected] [ Tool ] Fix `flutter upgrade` stating that an upgrade is available on `main` when up to date (flutter/flutter#172141)
2025-07-15 [email protected] Reland "Add feature flags to the framework" (flutter/flutter#171545)
2025-07-14 [email protected] chore: unskip tests cases (flutter/flutter#172031)
2025-07-14 [email protected] Route transition duration (flutter/flutter#171109)
2025-07-14 [email protected] [Impeller] libImpeller: Correctly release mappings created using the C++ API wrapper. (flutter/flutter#172136)
2025-07-14 [email protected] Roll Skia from 5f7adef2ac25 to 2f4ad5d83704 (3 revisions) (flutter/flutter#172134)
2025-07-14 [email protected] Migrate to arm based firebase test devices for api 26 and 27 (flutter/flutter#172128)
2025-07-14 [email protected] [web] Cleanup unnecessary dart defines and renderer in web tests (flutter/flutter#172130)
2025-07-14 [email protected] Use granular skparagraph targets (flutter/flutter#161676)
2025-07-14 [email protected] [ Widget Preview ] Initial work to support reacting to IDE events (flutter/flutter#172040)
2025-07-14 [email protected] Roll Skia from e95c92d867b5 to 5f7adef2ac25 (8 revisions) (flutter/flutter#172123)
2025-07-14 [email protected] [skia] Set GN flags explicitly for fuchsia build (flutter/flutter#172104)
2025-07-14 [email protected] fix: documentation around led launch broken (flutter/flutter#171983)
2025-07-14 [email protected] [ Tool ] Downgrade and pin DDS to 5.0.3 (flutter/flutter#172120)
2025-07-14 [email protected] Apply superellipse clipping to iOS platform views using an approximated round rect (flutter/flutter#172033)
2025-07-14 [email protected] [Impeller] Fix broken image links in documentation. (flutter/flutter#171465)
2025-07-14 [email protected] remove `x86` in CI  builder linux_android_emulator (flutter/flutter#170964)
2025-07-14 [email protected] remove `x86` in flutter_gdb (flutter/flutter#170966)
2025-07-14 [email protected] fix android studio lint about lambda function (flutter/flutter#172063)
2025-07-14 [email protected] Roll Fuchsia Linux SDK from qw0YTtPhosk3-rr4h... to tQAtsLtpc0oBIqRwC... (flutter/flutter#172116)
2025-07-14 [email protected] Roll Skia from 92354f64e37f to e95c92d867b5 (1 revision) (flutter/flutter#172111)
2025-07-14 [email protected] [web] Delete unused files in the engine (flutter/flutter#172035)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
1890c8a 
…r#171545)
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
d84e408 
…r#171545)
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
1dc8291 
…r#171545)
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
62a042d 
…r#171545)
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 16, 2025
@engine-flutter-autoroll
6474b04e6 Reland "Add feature flags to the framework" (flutter/flutte…
728216d 
…r#171545)
ksokolovskyi pushed a commit to ksokolovskyi/flutter that referenced this pull request Aug 19, 2025
@loic-sharma @ksokolovskyi
Reland "Add feature flags to the framework" (flutter#171545)
e4ccd43 
This relands flutter#168437. The google3
fixes were landed in: flutter#171547,
https://critique.corp.google.com/cl/781275353,
flutter#171933.

This PR is split into two commits:

1. d625379, code from
flutter#168437 without any changes
2. f35d29e, updates the PR to omit
obvious types.

Original PR description:

## Motivation

We'd like to let users opt-in to experimental features so that they can
give early feedback while we iterate on the feature. For example:

Example feature flags:

1. Android sensitive content:
flutter#158473. When enabled, Flutter
will tell Android when the view contains sensitive content like a
password.
3. Desktop multi-window. When enabled, Flutter will use child windows to
allow things like a context menu to "escape" outside of the current
window.

### Use case

Users will be able to turn on features by:

* **Option 1**: Run `flutter config --enable-my-feature`. This enables
the feature for all projects on the machine
* **Option 2**: Add `enable-my-feature: true` in their `pubspec.yaml`,
under the `flutter` section. This would enable the for a single project
on the machine.

Turning on a feature affects _both_ development-time (`flutter run`) and
deployment-time (`flutter build x`). For example, I can `flutter build
windows` to create an `.exe` with multi-window features enabled.

## How this works

This adds a new
[`runtimeId`](https://github.com/flutter/flutter/pull/168437/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R243-R247)
property to the tool's `Feature` class. If a feature is on and has a
`runtimeId`, its `runtimeId` will be [stamped into the Dart application
as a Dart
define](https://github.com/flutter/flutter/pull/168437/files#diff-bd662448bdc2e6f50e47cd3b20b22b41a828561bce65cb4d54ea4f5011cc604eR293-R327).
The framework uses this Dart define to [determine which features are
enabled](https://github.com/flutter/flutter/pull/168437/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45).

### Multi-window example

flutter#168697 shows how this new
feature flag system can be used to add a multi-window feature flag:

1. It adds a new [multi-window
feature](https://github.com/flutter/flutter/pull/168697/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R189-R198)
to the Flutter tool. This can be turned on using `flutter config
--enable-multi-window` or by putting `enable-multi-window: true` in an
app's .pubspec, under the `flutter` section.
2. It adds a new
[`isMultiWindowEnabled`](https://github.com/flutter/flutter/pull/168697/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45R7-R11)
property to the framework.
4. The Material library can use this new property to determine whether
it should create a new window.
[Example](https://github.com/flutter/flutter/pull/168697/files#diff-2cbc1634ed6b61d61dfa090e7bfbbb7c60b74c8abc3a28df6f79eee691fd1b73).

## Limitations

### Tool and framework only

For now, these feature flags are available only to the Flutter tool and
Flutter framework. The flags are not automatically available to the
embedder or the engine.

For example, embedders need to configure their surfaces differently if
Impeller is enabled. This configuration must happen before the Dart
isolate is launched. As a result, the framework's feature flags is not a
viable solution for this scenario for now. For these kinds of scenarios,
we should continue to use platform-specific configuration like the
`AndroidManifest.xml` or `Info.plist` files.

This is a fixable limitation, we just need to invest in this plumbing :)

### Tree shaking

Feature flags are not designed to help tree shaking. For example, you
cannot conditionally import Dart code depending on the enabled feature
flags. Code that is feature flagged off will still be imported into
user's apps.
mboetger pushed a commit to mboetger/flutter that referenced this pull request Sep 18, 2025
@loic-sharma @mboetger
Reland "Add feature flags to the framework" (flutter#171545)
cbc1a7e 
This relands flutter#168437. The google3
fixes were landed in: flutter#171547,
https://critique.corp.google.com/cl/781275353,
flutter#171933.

This PR is split into two commits:

1. d625379, code from
flutter#168437 without any changes
2. f35d29e, updates the PR to omit
obvious types.

Original PR description:

## Motivation

We'd like to let users opt-in to experimental features so that they can
give early feedback while we iterate on the feature. For example:

Example feature flags:

1. Android sensitive content:
flutter#158473. When enabled, Flutter
will tell Android when the view contains sensitive content like a
password.
3. Desktop multi-window. When enabled, Flutter will use child windows to
allow things like a context menu to "escape" outside of the current
window.

### Use case

Users will be able to turn on features by:

* **Option 1**: Run `flutter config --enable-my-feature`. This enables
the feature for all projects on the machine
* **Option 2**: Add `enable-my-feature: true` in their `pubspec.yaml`,
under the `flutter` section. This would enable the for a single project
on the machine.

Turning on a feature affects _both_ development-time (`flutter run`) and
deployment-time (`flutter build x`). For example, I can `flutter build
windows` to create an `.exe` with multi-window features enabled.

## How this works

This adds a new
[`runtimeId`](https://github.com/flutter/flutter/pull/168437/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R243-R247)
property to the tool's `Feature` class. If a feature is on and has a
`runtimeId`, its `runtimeId` will be [stamped into the Dart application
as a Dart
define](https://github.com/flutter/flutter/pull/168437/files#diff-bd662448bdc2e6f50e47cd3b20b22b41a828561bce65cb4d54ea4f5011cc604eR293-R327).
The framework uses this Dart define to [determine which features are
enabled](https://github.com/flutter/flutter/pull/168437/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45).

### Multi-window example

flutter#168697 shows how this new
feature flag system can be used to add a multi-window feature flag:

1. It adds a new [multi-window
feature](https://github.com/flutter/flutter/pull/168697/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R189-R198)
to the Flutter tool. This can be turned on using `flutter config
--enable-multi-window` or by putting `enable-multi-window: true` in an
app's .pubspec, under the `flutter` section.
2. It adds a new
[`isMultiWindowEnabled`](https://github.com/flutter/flutter/pull/168697/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45R7-R11)
property to the framework.
4. The Material library can use this new property to determine whether
it should create a new window.
[Example](https://github.com/flutter/flutter/pull/168697/files#diff-2cbc1634ed6b61d61dfa090e7bfbbb7c60b74c8abc3a28df6f79eee691fd1b73).

## Limitations

### Tool and framework only

For now, these feature flags are available only to the Flutter tool and
Flutter framework. The flags are not automatically available to the
embedder or the engine.

For example, embedders need to configure their surfaces differently if
Impeller is enabled. This configuration must happen before the Dart
isolate is launched. As a result, the framework's feature flags is not a
viable solution for this scenario for now. For these kinds of scenarios,
we should continue to use platform-specific configuration like the
`AndroidManifest.xml` or `Info.plist` files.

This is a fixable limitation, we just need to invest in this plumbing :)

### Tree shaking

Feature flags are not designed to help tree shaking. For example, you
cannot conditionally import Dart code depending on the enabled feature
flags. Code that is feature flagged off will still be imported into
user's apps.
lucaantonelli pushed a commit to lucaantonelli/flutter that referenced this pull request Nov 21, 2025
@loic-sharma @lucaantonelli
Reland "Add feature flags to the framework" (flutter#171545)
c043ffc 
This relands flutter#168437. The google3
fixes were landed in: flutter#171547,
https://critique.corp.google.com/cl/781275353,
flutter#171933.

This PR is split into two commits:

1. d625379, code from
flutter#168437 without any changes
2. f35d29e, updates the PR to omit
obvious types.

Original PR description:

## Motivation

We'd like to let users opt-in to experimental features so that they can
give early feedback while we iterate on the feature. For example:

Example feature flags:

1. Android sensitive content:
flutter#158473. When enabled, Flutter
will tell Android when the view contains sensitive content like a
password.
3. Desktop multi-window. When enabled, Flutter will use child windows to
allow things like a context menu to "escape" outside of the current
window.

### Use case

Users will be able to turn on features by:

* **Option 1**: Run `flutter config --enable-my-feature`. This enables
the feature for all projects on the machine
* **Option 2**: Add `enable-my-feature: true` in their `pubspec.yaml`,
under the `flutter` section. This would enable the for a single project
on the machine.

Turning on a feature affects _both_ development-time (`flutter run`) and
deployment-time (`flutter build x`). For example, I can `flutter build
windows` to create an `.exe` with multi-window features enabled.

## How this works

This adds a new
[`runtimeId`](https://github.com/flutter/flutter/pull/168437/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R243-R247)
property to the tool's `Feature` class. If a feature is on and has a
`runtimeId`, its `runtimeId` will be [stamped into the Dart application
as a Dart
define](https://github.com/flutter/flutter/pull/168437/files#diff-bd662448bdc2e6f50e47cd3b20b22b41a828561bce65cb4d54ea4f5011cc604eR293-R327).
The framework uses this Dart define to [determine which features are
enabled](https://github.com/flutter/flutter/pull/168437/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45).

### Multi-window example

flutter#168697 shows how this new
feature flag system can be used to add a multi-window feature flag:

1. It adds a new [multi-window
feature](https://github.com/flutter/flutter/pull/168697/files#diff-0ded384225f19a4c34d43c7c11f7cb084ff3db947cfa82d8d52fc94c112bb2a7R189-R198)
to the Flutter tool. This can be turned on using `flutter config
--enable-multi-window` or by putting `enable-multi-window: true` in an
app's .pubspec, under the `flutter` section.
2. It adds a new
[`isMultiWindowEnabled`](https://github.com/flutter/flutter/pull/168697/files#diff-c8dbd5cd3103bc5be53c4ac5be8bdb9bf73e10cd5d8e4ac34e737fd1f8602d45R7-R11)
property to the framework.
4. The Material library can use this new property to determine whether
it should create a new window.
[Example](https://github.com/flutter/flutter/pull/168697/files#diff-2cbc1634ed6b61d61dfa090e7bfbbb7c60b74c8abc3a28df6f79eee691fd1b73).

## Limitations

### Tool and framework only

For now, these feature flags are available only to the Flutter tool and
Flutter framework. The flags are not automatically available to the
embedder or the engine.

For example, embedders need to configure their surfaces differently if
Impeller is enabled. This configuration must happen before the Dart
isolate is launched. As a result, the framework's feature flags is not a
viable solution for this scenario for now. For these kinds of scenarios,
we should continue to use platform-specific configuration like the
`AndroidManifest.xml` or `Info.plist` files.

This is a fixable limitation, we just need to invest in this plumbing :)

### Tree shaking

Feature flags are not designed to help tree shaking. For example, you
cannot conditionally import Dart code depending on the enabled feature
flags. Code that is feature flagged off will still be imported into
user's apps.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@matanlurey matanlurey matanlurey approved these changes

@bkonyi bkonyi bkonyi approved these changes

Assignees

No one assigned

Labels

c: contributor-productivity Team-specific productivity, code health, technical debt. d: docs/ flutter/flutter/docs, for contributors framework flutter/packages/flutter repository. See also f: labels. tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@loic-sharma @matanlurey @bkonyi