
# 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

```yaml
# 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`:

```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):

```yaml
# neon_farum_azula: lib/resources/application.yml
spring:
  flutter:
    web:
      dev-server:
        port: 5110
```

and gets a file with the header above and:

```yaml
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:

- `application.*`, then `application-web.*`;
- the files of the profiles that `spring.profiles.active` names in them, with `include`, `default` and `group` handled as the app handles them;
- the files that `spring.config.import` names: relative paths and `resources:` locations, from `lib/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:

```text
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:

```yaml
# lib/resources/application-web.yaml
spring:
  flutter:
    security:
      web:
        mode: spa
```

```yaml
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 an `issuer-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:

```yaml
# 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](page-loader.md). 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

- [The page loader](page-loader.md)
- [Pages for search engines](seo.md)
- [Properties the build reads](../build-properties.md)
- [Profiles](../../spring-core-dart/config/profiles.md)
- [Placeholders](../../spring-core-dart/config/placeholders.md)
