The web dev server
The spring_flutter_web builder writes web_dev_config.yaml, the file flutter run -d chrome and flutter run -d web-server read, from the spring.flutter.web.dev-server.* properties of lib/resources/. You set the port, the host, HTTPS, headers and proxy rules where the rest of the app's configuration lives, and the Flutter tool uses them.
Why
Without configuration, the Flutter tool serves the web version on a random port. Many things need a fixed origin: a server's CORS list, the redirect back after an SSO login, a bookmark. Since Flutter 3.38 the dev server reads web_dev_config.yaml in the project directory, and nothing else configures it. Its command-line flags (--web-port, --web-hostname) still win over the file.
Writing that file by hand means a second place for values the app's configuration already knows. The builder writes it for you, keeps it in step with the properties, and deletes it when the properties are gone.
The app itself does not read these keys, and flutter build web does not use them: they configure the development server only.
Example
# lib/resources/application-web.yaml
spring:
flutter:
web:
dev-server:
host: localhost
port: 5050
base-href: /shop/
headers:
Cross-Origin-Opener-Policy: same-origin
proxy:
- prefix: /api/
target: http://localhost:8080
- regex: ^/auth/(.*)
target: http://localhost:9000
replace: /$1
dart run build_runner build writes, next to pubspec.yaml:
# GENERATED FILE - DO NOT MODIFY BY HAND.
#
# Written by spring_core_dart_generator from the
# spring.flutter.web.dev-server.* properties in lib/resources/
# (application.yaml, application-web.yaml,
# ...). Change those properties instead: this file is rewritten on
# every build, and deleted when the properties are removed.
# The Flutter tool reads it when it runs the web version
# (flutter run -d chrome / -d web-server); --web-port and the other
# flags still win over it.
server:
host: "localhost"
port: 5050
headers:
- name: "Cross-Origin-Opener-Policy"
value: "same-origin"
proxy:
- prefix: "/api/"
target: "http://localhost:8080"
- regex: "^/auth/(.*)"
target: "http://localhost:9000"
replace: "/$1"
base-href: "/shop/"
The sections always come in this order: host, port, https, headers, proxy, base-href. Texts are written as JSON strings, so a value can never break the YAML. A section without a value is left out.
This site sets only a port, in application.yml (the file without a profile is read in a browser too):
# neon_farum_azula: lib/resources/application.yml
spring:
flutter:
web:
dev-server:
port: 5110
and gets a file with the header above and:
server:
port: 5110
Forwarding /api/ to the server is the simplest way to avoid CORS and third-party cookie trouble in development: the page and the API share one origin, so a session login works in every browser.
When the builder writes, and when it stays silent
The builder runs for every package that depends on the generator, pure Dart servers too. So it must never fail or talk in a package that does not use the dev server. It decides in four steps.
- A quick look, without loading the configuration. It parses every
.properties,.ymland.yamlfile oflib/resources/, every document, whatever profile it belongs to. It also parses a file that an import names with a file hint, such asresources:dev.conf[.yaml]orresources:web.properties[encoding=iso-8859-1], in that format and encoding (a file that is not UTF-8 is read only this way). A placeholder in such an import is resolved with its default or with a value of the files (resources:${ENV:dev}.conf[.yaml]); one that only the running app knows (resources:${ENV}.conf[.yaml]) cannot be followed, so keys set only in that file do not count. - Old keys fail the build. A key under
spring.flutter.web.that is not underdev-server,seoorpageis a dev server key from before version 0.7.1. The build fails and names it:spring.flutter.web.port (lib/resources/application-web.yaml): the dev server's keys moved under spring.flutter.web.dev-server; write spring.flutter.web.dev-server.port. - Nothing to do. When no file sets a
spring.flutter.web.dev-server.*key orspring.flutter.security.web.mode, the configuration is not loaded at all. Nothing is written, a file the builder generated earlier is deleted, and nothing else in the configuration (an import, a placeholder, a file that does not parse) is the builder's business: the app's own start reports it. One exception: while a generatedweb_dev_config.yamlexists, a config file that does not parse may be the one that held the keys, so the configuration is loaded, and if the app reads that file, the build fails and the generated file is kept. - The real reading. Otherwise the configuration is loaded the way the app loads it in a browser (next section), and the
spring.flutter.web.dev-server.*values are taken from the result. If the loaded configuration holds none of them (for example, they are only in the file of a profile that is not active) and the app is not in spa mode, there is nothing to write, and a generated file is deleted.
How the configuration is read
The builder uses the same configuration loader as the application, with the web platform profile active:
application.*, thenapplication-web.*;- the files of the profiles that
spring.profiles.activenames in them, withinclude,defaultandgrouphandled as the app handles them; - the files that
spring.config.importnames: relative paths andresources:locations, fromlib/resources/; - placeholders resolved from these files, relaxed names matched as the app matches them.
What the build cannot know is left out on purpose:
| Case | What the builder does |
|---|---|
Environment variables and --dart-define values |
Not read. The build must not depend on the machine it runs on |
A profile name with a placeholder only they resolve, in spring.profiles.active, .include, .default or .group.* |
Left out, whatever else the name holds (dev,${ENV}-eu is read as dev), with a warning. A default (${APP_PROFILE:dev}) is used |
spring.profiles.validate or spring.main.cloud-platform with such a placeholder |
Read as unset, with a warning |
| An import location with such a placeholder | Not read (the other entries of its ; group are), with a warning |
A document whose spring.config.activate.on-profile or .on-cloud-platform has such a placeholder |
Skipped, with a warning |
A file:, configtree: or package: import, or an absolute path, with or without a wildcard |
Skipped, optional: or not: a browser has no file system. When there is a file to write, a warning names the first required one, because the web version would fail to start with it |
An asset:, http: or https: import, or a resources: file missing from lib/resources/ |
Skipped silently, even a required one: it may exist at run time |
Where a key may appear is still checked: spring.profiles.active in application-web.yaml fails the build whatever its value, as it fails the app's start. A placeholder inside a spring.flutter.web.dev-server.* value, or in spring.flutter.security.web.mode, must resolve at build time, or the build fails:
spring.flutter.web.dev-server.port (in lib/resources/application-web.yaml): '${PORT}' cannot be
resolved at build time (...). The dev server is configured when the app is built, so only config
files count, not --dart-define or environment variables.
When the same key is set in several files, the file that wins in the app wins here too: application-web.yaml over application.yaml, a profile's file over both. Headers merge across files, the winning file deciding each header (names compared without case). The proxy list comes whole from the winning file that has one, as lists do in Spring Boot.
A file written by hand
web_dev_config.yaml is not a declared build output. If it were, build_runner would overwrite a hand-written file of that name, and delete the file whenever the builder stopped writing it. So the builder manages the file itself, and only ever changes a file whose first line is # GENERATED FILE - DO NOT MODIFY BY HAND.:
| Properties | The file on disk | Result |
|---|---|---|
| Set | None, or a generated one | The file is written; it is only rewritten when its text changes |
| Set | Written by hand | The build fails and asks you to remove one of them; the file is left alone |
| None | Generated | The file is deleted |
| None | Written by hand | Nothing happens |
| An invalid value | Any | The build fails and names the property; the file is left as it is |
| A config file the app reads does not parse | Any | The build fails; the file is left as it is |
To switch from a hand-written file to the properties, delete the file, then run dart run build_runner clean or change a file in lib/resources/.
When it runs again
build_runner runs the builder again when a file of lib/resources/ changes. It does not watch web_dev_config.yaml, which is no build source: if you delete the file, it comes back only after dart run build_runner clean or a change in lib/resources/.
Properties
All keys are optional. The table gives the key below spring.flutter.web.dev-server..
| Key | Type | Default | Written as | Meaning |
|---|---|---|---|---|
host |
text, not empty | the Flutter tool's | server.host |
The address to listen on: localhost, or 0.0.0.0 for other devices on the network |
port |
integer, 0 to 65535 | a free port | server.port |
The port. 0 picks a free one |
base-href |
path starting and ending with / |
/ |
server.base-href |
The path the app is served under (/shop/) |
https.cert-path |
file path | none (HTTP) | server.https.cert-path |
The TLS certificate (PEM). Set it with cert-key-path, or neither |
https.cert-key-path |
file path | none | server.https.cert-key-path |
The certificate's private key (PEM) |
headers.<Name> |
text | none | server.headers |
A header added to every response |
proxy[n].target |
absolute URL | none | server.proxy[n].target |
Where the requests of rule n go (http://localhost:8080). Required in every rule |
proxy[n].prefix |
path | none | server.proxy[n].prefix |
Rule n matches paths that start with it (/api/) |
proxy[n].regex |
regular expression | none | server.proxy[n].regex |
Or the paths that match it. Each rule sets exactly one of prefix and regex |
proxy[n].replace |
text | the path unchanged | server.proxy[n].replace |
The forwarded path: the matched part replaced, $1 for the first group |
content-security-policy |
text, not empty | none; in spa mode, a ready policy | a header | The page's Content Security Policy, sent as Content-Security-Policy |
content-security-policy-report-only |
true / false |
false |
the header's name | Send the policy as Content-Security-Policy-Report-Only: violations are logged in the console, nothing is blocked |
content-security-policy-connect-src |
list of origins | none | inside the policy | Origins added to connect-src of spa mode's ready policy |
The builder also reads spring.flutter.security.web.mode (spa mode, below), the spring.security.oauth2.client.* keys (the origins of spa mode's policy), and, for an app that depends on spring_boot_starter_flutter, the theme's splash (to allow the page loader's script).
Checks
| Problem | Result |
|---|---|
https.cert-path without https.cert-key-path, or the other way round |
Build error: HTTPS needs both https.cert-path and https.cert-key-path |
host empty |
Build error |
port not an integer from 0 to 65535 |
Build error |
port that browsers refuse (ERR_UNSAFE_PORT: 1, 22, 25, 5060, 6000, 6665 to 6669, 10080 and the rest of the Fetch standard's list) |
Warning: the app would not open in a browser |
base-href that does not start and end with / |
Build error |
A proxy rule without target, or with a target that is not an absolute URL |
Build error |
A proxy rule with both or neither of prefix and regex |
Build error |
A regex that is not a valid regular expression |
Build error, with the parser's message |
content-security-policy empty |
Build error |
content-security-policy and headers.Content-Security-Policy (or -Report-Only) both set |
Build error: keep one |
content-security-policy-report-only not true or false |
Build error |
content-security-policy-connect-src with an entry that is not an origin (https://api.example.com, wss://api.example.com) |
Build error |
content-security-policy-connect-src next to an own policy |
Build error: put the origins into that policy |
content-security-policy-connect-src without spa mode |
Warning: it is ignored |
An unknown spring.flutter.web.dev-server.* key (prot) |
Warning listing the known keys; nothing else changes |
The Content Security Policy
A Content Security Policy tells the browser which scripts, styles and connections the page may use, so a script injected into it is refused. With content-security-policy set, every answer of flutter run carries it, so development runs under the policy that production sends.
An app whose browser logs in by itself (spring.flutter.security.web.mode: spa) and sets no policy gets a ready one. The builder writes a file for it even without any dev-server key:
# lib/resources/application-web.yaml
spring:
flutter:
security:
web:
mode: spa
server:
headers:
- name: "Content-Security-Policy"
value: "default-src 'self'; script-src 'self' 'wasm-unsafe-eval' https://www.gstatic.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://www.gstatic.com https://fonts.gstatic.com; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'"
Each part is there for Flutter's web engine, and nothing more:
| Directive | Why |
|---|---|
script-src 'self' 'wasm-unsafe-eval' https://www.gstatic.com |
The app's scripts, and CanvasKit from Flutter's CDN; 'wasm-unsafe-eval' compiles the WebAssembly of CanvasKit and Skwasm. No JavaScript eval, no inline scripts |
style-src 'self' 'unsafe-inline' |
Flutter's engine writes a <style> element |
font-src and connect-src with https://fonts.gstatic.com |
The fallback fonts, which the engine fetches |
worker-src 'self' blob: |
Skwasm's workers |
img-src 'self' data: blob: |
Images of the app |
object-src 'none', base-uri 'self', form-action 'self', frame-ancestors 'none' |
No plugins, no foreign <base> or form targets, no framing by other sites |
connect-src also gets the origins the login fetches from that the build can know:
- the origins of every
spring.security.oauth2.client.provider.<id>URI (issuer, token, user info, keys); - the built-in endpoints of a Google, GitHub, Facebook or Apple registration that has no provider section of its own (Google's
https://www.googleapis.com), except those its own section replaces; none when the section has anissuer-uri; - for an issuer of Google or Microsoft, the hosts their discovery documents name besides the issuer (
https://oauth2.googleapis.com,https://openidconnect.googleapis.com,https://www.googleapis.com;https://graph.microsoft.com); - then the origins of
content-security-policy-connect-src.
The authorization endpoint is not in the list: the page navigates there, it does not fetch it. Another issuer's discovery document is read at run time, so an endpoint it names on another host is unknown to the build. List that host in content-security-policy-connect-src, with the APIs the app calls:
# lib/resources/application-web.yaml
spring:
flutter:
web:
dev-server:
content-security-policy-connect-src:
- https://api.neon.books
- wss://api.neon.books
When the app depends on spring_boot_starter_flutter and its active theme has a splash, web/index.html holds the inline script of the page loader. The ready policy then adds that script's hash to script-src. It also adds the hashes of the inline scripts that spring.flutter.web.page.swipe-to-close: false and spring.flutter.web.page.max-pixel-ratio write into the page, when they are set. Each script is written with nothing else between its tags, so the hash the browser computes matches. With your own policy, add the hashes yourself (WebPageLoader.scriptHash, WebPageHead.hashOf).
Hot reload evaluates code in debug runs, which a strict policy forbids. Use content-security-policy-report-only: true in a development profile when it gets in the way. The dev server is not production: send the same policy from the server or CDN that serves build/web.
In Spring (Java)
Spring has no equivalent. A Spring Boot web application is its own server (server.port), and its development tools need no separate file. The builder exists because a Flutter web app is served by the Flutter tool during development, not by the app.