<!--
Thanks for filing a pull request!
Reviewers are typically assigned within a week of filing a request.
To learn more about code review, see our documentation on Tree Hygiene:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
-->
## Add --web-define option for runtime variable injection in Flutter web
templates
This PR adds support for injecting environment-specific variables into
Flutter web templates during development and build processes through a
new `--web-define` command-line option.
### What this changes
**Before**: Developers had to manually edit HTML templates or use
build-time workarounds to inject environment-specific values (API URLs,
feature flags, etc.) into Flutter web applications.
**After**: Developers can now use `--web-define KEY=VALUE` to inject
variables directly into web templates using `{{VARIABLE_NAME}}`
placeholders.
### Key features
- **Template variable substitution**: Support for `{{VARIABLE_NAME}}`
placeholders in `index.html` and `flutter_bootstrap.js`
- **Runtime validation**: Throws clear errors when required variables
are missing with helpful suggestions
- **Command-line integration**: Works with both `flutter run` and
`flutter build web` commands
- **Multiple variable support**: Can define multiple variables in a
single command
- **Built-in variable protection**: Ignores Flutter's built-in template
variables during validation
### Usage examples
```bash
# Development with API configuration
flutter run -d chrome --web-define=API_URL=https://dev-api.example.com --web-define=DEBUG_MODE=true
# Production build with environment variables
flutter build web --web-define=API_URL=https://api.example.com --web-define=ANALYTICS_ID=GA-123456 --web-define=DEBUG_MODE=false
# Multiple environments
flutter run -d chrome --web-define=ENV=staging --web-define=FEATURE_X=enabled
```
### Template usage
In your `web/index.html`:
```html
<script>
window.config = {
apiUrl: '{{API_URL}}',
environment: '{{ENV}}',
debugMode: {{DEBUG_MODE}}
};
</script>
```
### Error handling
If a variable is missing, the tool provides clear feedback:
```
Missing web-define variable: API_URL
Please provide the missing variable using:
flutter run --web-define=API_URL=VALUE
or
flutter build web --web-define=API_URL=VALUE
```
## Issues fixed
Fixes https://github.com/flutter/flutter/issues/127853
## Additional Usage Examples
### Environment-Specific Configurations (Flavors)
```bash
# Development
flutter run -d chrome --web-define=ENV=dev --web-define=API_URL=http://localhost:3000 --web-define=DEBUG=true
# Production
flutter build web --web-define=ENV=prod --web-define=API_URL=https://api.example.com --web-define=DEBUG=false
```
**Template:**
```html
<script>
window.config = {
environment: '{{ENV}}',
apiUrl: '{{API_URL}}',
debugMode: {{DEBUG}}
};
</script>
```
### Dynamic Asset Loading
```bash
flutter build web --web-define=CDN_URL=https://cdn.example.com --web-define=LOGO_PATH=/assets/logo.png
```
**Template:**
```html
<link rel="icon" href="{{CDN_URL}}{{LOGO_PATH}}">
<link rel="stylesheet" href="{{CDN_URL}}/styles/theme.css">
```
### Analytics Integration
```bash
flutter build web --web-define=GA_ID=G-XXXXXXXXXX --web-define=SENTRY_DSN=https://xxx@sentry.io/123
```
**Template:**
```html
<script async src="https://www.googletagmanager.com/gtag/js?id={{GA_ID}}"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '{{GA_ID}}');
</script>
```
### Feature Flags
```bash
flutter run -d chrome --web-define=FEATURE_X=true --web-define=FEATURE_Y=false
```
**Template:**
```html
<script>
window.features = { featureX: {{FEATURE_X}}, featureY: {{FEATURE_Y}} };
</script>
```
### Multi-Tenant/White-Label Apps
```bash
flutter build web --web-define=TENANT=acme --web-define=PRIMARY_COLOR=#FF5733 --web-define=LOGO_URL=https://cdn.acme.com/logo.png
```
**Template:**
```html
<head>
<title>{{TENANT}} Portal</title>
<link rel="icon" href="{{LOGO_URL}}">
<style>:root { --primary: {{PRIMARY_COLOR}}; }</style>
</head>
```
### Backend Service URLs
```bash
flutter build web \
--web-define=API_URL=https://api.example.com \
--web-define=WS_URL=wss://ws.example.com \
--web-define=AUTH_DOMAIN=auth.example.com
```
**Template:**
```html
<script>
window.services = {
api: '{{API_URL}}',
websocket: '{{WS_URL}}',
auth: '{{AUTH_DOMAIN}}'
};
</script>
```
### SEO & Meta Tags
```bash
flutter build web --web-define=APP_TITLE="My App" --web-define=APP_DESC="Description" --web-define=OG_IMAGE=https://example.com/og.png
```
**Template:**
```html
<head>
<title>{{APP_TITLE}}</title>
<meta name="description" content="{{APP_DESC}}">
<meta property="og:title" content="{{APP_TITLE}}">
<meta property="og:image" content="{{OG_IMAGE}}">
</head>
```
### Build Automation
```json
{
"scripts": {
"dev": "flutter run -d chrome --web-define=ENV=dev --web-define=API_URL=http://localhost:3000",
"prod": "flutter build web --web-define=ENV=prod --web-define=API_URL=https://api.example.com"
}
}
```
### Important Notes
- **Security**: Never expose secrets via `--web-define` (client-side
only)
## 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].
**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.
<!-- 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
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Ben Konyi <bkonyi@google.com>
Co-authored-by: Mouad Debbar <mdebbar@google.com>
This PR restores the correct precedence behavior for web development
server configuration. Since Flutter 3.38, CLI arguments were being
ignored when `web_dev_config.yaml` was present — specifically for HTTPS
and headers.
According to the design and documentation, the precedence should be:
1. Command-line arguments (highest priority)
2. `web_dev_config.yaml`
3. Built-in defaults (lowest priority)
## Root Cause
The regression affected:
* **HTTP headers** — merge order was reversed, causing file config to
override CLI
* **HTTPS config** — CLI TLS arguments were ignored under certain
conditions
Note:
`--web-port` and `--web-hostname` were already working correctly due to
the `host ?? this.host` and `port ?? this.port` pattern.
The observed issue was due to headers + HTTPS only.
## Changes Made
* Fixed header merge order so CLI takes precedence
* Corrected HTTPS config resolution and precedence logic
* Unified logic across `run` and `drive` commands
* Simplified HTTPS handling using `HttpsConfig.parse()`
* Added tests for CLI precedence behavior
## Before (broken)
```
flutter run -d chrome --web-tls-cert-path cert.pem
```
❌ CLI TLS args ignored when config file existed
❌ headers overridden by file config
## After (fixed)
```
flutter run -d chrome --web-tls-cert-path cert.pem
```
✅ CLI TLS args respected
✅ headers override config as expected
## Tests
* Added tests verifying CLI takes precedence
* All existing and new tests pass
* No breaking changes introduced
## Fixes
Fixes: #179014
---------
Co-authored-by: Kevin Moore <kevmoo@google.com>
Co-authored-by: Kevin Moore <kevmoo@users.noreply.github.com>
Co-authored-by: Ben Konyi <bkonyi@google.com>
Fixes https://github.com/flutter/flutter/issues/163479
This adds a flag,
`--cross-origin-isolation`/`--no-cross-origin-isolation` that allows the
user to explicitly control whether `flutter run`/`drive`/`test` serves
files with COOP/COEP headers. If the user doesn't specify, it uses cross
origin isolation when wasm is enabled and no cross origin isolation when
wasm is disabled.
Move getFinalTargetUri to ProxyRule class
Fix doc comments
Pares URI immediately when creating RegexProxyRule
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Exceptions thrown within a stream transformer don't provide any context
as to where the call to `transform(...)` occurred within the program,
often resulting in stack traces consisting of only Dart SDK sources.
This change adds a new extension method on `Stream` called
`transformWithCallSite`, which captures the current `StackTrace` upon
invocation. This stack trace is reported in the case of an error in
order to provide context for better error reporting.
Example issue: https://github.com/flutter/flutter/issues/81666
This PR contains the initial work to prepare for the removal of
instances of DevTools being served manually by the flutter_tool, instead
relying on DDS to serve DevTools. This will be consistent with how the
standalone Dart VM serves DevTools, tying the DevTools lifecycle to a
live DDS instance. This will allow for the removal of much of the logic
needed to properly manage the lifecycle of the DevTools server in a
future PR. Also, by serving DevTools from DDS, users will no longer need
to forward a secondary port in remote workflows as DevTools will be
available on the DDS port.
There's two remaining circumstances that will prevent us from removing
`DevtoolsRunner` completely:
- The daemon's `devtools.serve` endpoint
- `flutter drive`'s `--profile-memory` flag used for recording memory
profiles
DWDS 25.0.1 requires that a valid reloadedSourcesUri is passed and
updated for both a hot restart and a hot reload. Therefore, the
bootstrap scripts which use it as well as the code to write that file is
updated. Note that this file is read in both DWDS and in the bootstrap
script. Along with this, code is fixed to update modules and digests
regardless of a full restart. Currently, it makes no difference as
neither Flutter tools or DWDS makes use of the updated modules or
digests with the new library bundle format, but it's updated for
consistency.
## 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].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [ ] 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.
Closes https://github.com/flutter/flutter/issues/171637
As mentioned in the issue, I am proposing a new argument to the flutter
build web command: `--static-assets-url`.
This argument would accept a full URL string ending with `/` as its
value. During the build process, the Flutter tool would use this value
to replace a dedicated placeholder within the `web/index.html` file
(inspired by `--base-href` approach).
Example Implementation:
A developer would modify their `web/index.html` to use a new
placeholder, for instance, `$FLUTTER_STATIC_ASSETS_URL`:
```html
...
<body>
<script>
{{flutter_js}}
{{flutter_build_config}}
_flutter.loader.load({
config: {
entryPointBaseUrl: "$FLUTTER_STATIC_ASSETS_URL",
},
onEntrypointLoaded: async function (engineInitializer) {
const appRunner = await engineInitializer.initializeEngine({
assetBase: "$FLUTTER_STATIC_ASSETS_URL",
});
await appRunner.runApp();
},
});
</script>
</body>
...
```
The build command would be run with the new flag: `flutter build web --static-assets-url="https://static.company.com/some-webapp/“` - and the resulting `build/web/index.html` would have the placeholder replaced:
```html
...
<body>
<script>
{{flutter_js}}
{{flutter_build_config}}
_flutter.loader.load({
config: {
entryPointBaseUrl: "https://static.company.com/some-webapp/",
},
onEntrypointLoaded: async function (engineInitializer) {
const appRunner = await engineInitializer.initializeEngine({
assetBase: "https://static.company.com/some-webapp/",
});
await appRunner.runApp();
},
});
</script>
</body>
...
```
We already use the baseUri when computing hot reload sources metadata as
it can never be null. The member is changed to be non-nullable to
reflect that.
To be consistent, we also use the baseUri (full url) for a hot restart
when running with the DDC library bundle format.
Related PR: https://github.com/dart-lang/webdev/pull/2650
## 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].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [ ] 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.
Sources under `packages/flutter_tools/` aren't accessible to the average
Flutter user by navigating through sources from their projects, so it
doesn't need to be as explicitly verbose with types for readability
purposes. The `always_specify_types` lint results in extremely verbose
code within the tool which adds little value.
This change disables `always_specify_types` in favor of a new set of
lints that aim to reduce verbosity by removing obvious types while also
maintaining readability in cases where variable types otherwise wouldn't
be obvious:
- `omit_obvious_local_variable_types`
- `omit_obvious_property_types`
- `specify_nonobvious_local_variable_types`
- `specify_nonobvious_property_types`
Example message with findings:
```
Wasm dry run findings:
Found incompatibilities with WebAssembly.
package:counter1/main.dart 3:1 - dart:html unsupported (0)
Consider addressing these issues to enable wasm builds. See docs for more info: https://docs.flutter.dev/platform-integration/web/wasm
Compiling lib/main.dart for the Web... 10.9s
✓ Built build/web
```
Example message without findings:
```
Wasm dry run succeeded. Consider building and testing your application with the `--wasm` flag. See docs for more info: https://docs.flutter.dev/platform-integration/web/wasm
Compiling lib/main.dart for the Web... 10.8s
✓ Built build/web
```
---------
Co-authored-by: Nate Biggs <natebiggs@google.com>
Provides extra minification controls for web builds. Updates the
existing `--minify` flag to pass its value to both JS and wasm (instead
of just JS).
Also adds two new flags `--minify-js` and `--minify-wasm` which toggle
minification for just one of the web targets. While JS minification has
a huge impact on code size, wasm minification has a much smaller effect
on the program's size. Since minification can obfuscate useful info
(like errors) one may want to turn off minification for wasm but leave
it on for JS.
The plan is to temporarily use `--no-minify-wasm` for devtools to help
debug some exceptions being seen.
---------
Co-authored-by: Nate Biggs <natebiggs@google.com>
Possible fix for https://github.com/flutter/flutter/issues/169574
It looks like the timeouts seem to be specific to downloading scripts.
Specifically, after a certain point, we no longer download any scripts.
Lowering the number of max concurrent requests seems to avoid Chrome
timing out.
This does a refactor as well to make sure we're piping FileSystem,
Logger, and Platform into devfs_web.dart instead of relying on globals
every time. This also fixes a test issue where we were always passing
`isWindows: false` in some test cases instead of checking for the value.
## 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.
This PR makes the following improvements to web hot reload support and
related tests:
- The `--start-paused` flag is now silently added when running with `-d
web-server --web-experimental-hot-reload` if it is not already present.
- Refactored test infrastructure to allow specifying the device
parameter (e.g., `'chrome'`, `'web-server'`) when running integration
tests.
- Added a new `web_run_web_server_test` to run flows on the web-server
device.
- Updated existing tests to explicitly pass the correct device parameter
where needed.
- We are currently not able to test hot reload on the web-server device
as this is not yet supported.
Fixes https://github.com/dart-lang/sdk/issues/60289
In the case of a multi-app scenario, different applications may store
files in different locations. In order to avoid reloading files that
were unchanged, a suffix can be added to indicate which "version" of
this file we're loading. Even if it has a different path, because the id
and "version" (which is URL(...).search) are the same, the file would
not be reloaded.
With Flutter tools, this scenario doesn't occur. The running application
ultimately does not need to worry about the same file in different
locations.
The benefit to avoid this caching is that the user only ever sees one
copy of every file, which is the latest version, instead of the current
behavior where a "gen=N" suffix is added to a newer version.
Note that this is unrelated to the XHR or its headers or any of its
caching mechanisms. The XHR is only used to fetch the *list* of changed
files, not the files themselves. The files get loaded as part of the
`appendChild` call.
https://github.com/flutter/flutter/issues/166294
## 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 `///`).
- [ ] 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.
The path to reload scripts JSON was being added to the global window
before. It should instead be passed to the provider on setup. In order
to do this, the baseUri calculation is moved into the WebAssetServer.
This is safe because Flutter tools was calculating it immediately
after creating the server anyways.
https://github.com/dart-lang/webdev/issues/2584
Existing hot reload tests should test this behavior.
## 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 `///`).
- [ ] 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.
- [ ] All existing and new tests are passing.
The existing code assumed that DWDS needed to initialize some of the JS
state between adding all the scripts to queue and when they are loaded.
A closer examination of the existing AMD module format bootstrapper
shows that we already only initialize DWDS' JS state after all the
scripts are loaded. This is because it waits for the entrypoint to be
loaded before initializing that state, and the entrypoint is only loaded
after all its dependencies are loaded, which includes the SDK and
transitively every file in the app.
Since it's simpler and avoids the double-gating to call main, this
change moves that initialization to after all the scripts are loaded and
aligns with the AMD module bootstrapper.
## 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 `///`).
- [ ] 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.
`flutter widget-preview start --web` will cause the widget preview
scaffold to be run as a Flutter Web application using experimental hot
reload support. This will eventually be the default, with the desktop
environment being put behind a flag for use as a fallback under the
assumption that the desktop environment will be removed in the future.
- Adds better instructions for hot reload (if using the right flags),
hot restart, quitting, clearing, and more. These were already being
printed when using the VM, so this aligns with that.
- Adds an extra parameter for `CommandHelp` to `ResidentRunner` so
`ResidentWebRunner` can pass a version of it that uses its separate
logger and not `globals`. In order to support this, classes up the stack
also provide a `Terminal`, `Platform`, and `OutputPreferences`.
- Fixes up use of `globals` from an earlier change to implement hot
reload to use the logger instead. Same with `globals.platform`.
- Adds tests to check that only hot restart is printed when not using
the extra front-end flags, and both hot restart and hot reload is
printed when you are.
## 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.
- Delete code paths that handle screenshots for the HTML renderer
- Delete artifact enums for the HTML/AUTO renderers (and all their
usages).
- Remove HTML/AUTO renderers warnings.
- Delete the HTML/AUTO renderer enums (and all their usages).
- Delete tests for all the above.
Towards https://github.com/flutter/flutter/issues/162846.
Removes all of the unsound host artifacts, and then uses their name for
the sound artifacts.
That is, for something like `webPlatformDDCKernelDill`, this PR:
- Changes the web GN builders to only emit the sound SDK, without the
`-sound` suffixes
- Deletes `webPlatformDDCKernelDill` and all usages of it (implicitly
unsound, and unused).
- Renames `webPlatformDDCKernelSoundDill` to `webPlatformDDCKernelDill`.
No user impact expected, as there was no way to use the unsound
artifacts from the Flutter tool.
