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.

  1. A quick look, without loading the configuration. It parses every .properties, .yml and .yaml file of lib/resources/, every document, whatever profile it belongs to. It also parses a file that an import names with a file hint, such as resources:dev.conf[.yaml] or resources: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.
  2. Old keys fail the build. A key under spring.flutter.web. that is not under dev-server, seo or page is 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.
  3. Nothing to do. When no file sets a spring.flutter.web.dev-server.* key or spring.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 generated web_dev_config.yaml exists, 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.
  4. 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:

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 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.

See also