From 9d6f3b3b72e7d3d21b16cf0b2e78c996bf57911c Mon Sep 17 00:00:00 2001 From: Sydney Bao Date: Tue, 22 Jul 2025 18:51:54 -0700 Subject: [PATCH 01/12] add web-dev-config-file --- .../web/web-dev-config-file.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 src/content/platform-integration/web/web-dev-config-file.md diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md new file mode 100644 index 0000000000..b44d1ebe98 --- /dev/null +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -0,0 +1,100 @@ +--- +title: Set up a web development configuration file +description: Centralize web development settings including a development proxy +short-title: Web development configuration +--- + +# Set up a web development configuration file +**By Sydney Bao** + +Flutter web includes a development server that defaults to serving your application in the `localhost` domain via HTTP on a randomly assigned port. While command-line arguments offer a quick way to modify the server’s behavior, this document focuses on a more structured approach: defining your server's behavior through a centralized `web_dev_config.yaml` file. This configuration file allows you to customize server settings---host, port, HTTPS settings, and proxy rules---ensuring a consistent development environment. + +## Create a configuration file + +Add a `web_dev_config.yaml` file in the root directory of your Flutter project. If you haven’t set up a Flutter project, visit [Building a web application with Flutter](https://docs.flutter.dev/platform-integration/web/building) to get started. + +## Add configuration settings + +### Basic server configuration + +You can define the host, port, and HTTPS settings for your development server! + +```yaml +#web_dev_config.yaml +server: + host: "0.0.0.0" # Defines the binding address + port: 8080 # Specifies the port for the development server + https: + cert-path: "/path/to/cert.pem" # Path to your TLS certificate + cert-key-path: "/path/to/key.pem" # Path to TLS certificate key +``` + +### Custom headers + +You can also inject custom HTTP headers into the development server’s responses! + +```yaml +#web_dev_config.yaml +server: + headers: + - name: "X-Custom-Header" # Name of the HTTP header + value: "MyValue" # Value of the HTTP header + - name: "Cache-Control" + value: "no-cache, no-store, must-revalidate" +``` + +### Proxy configuration + +Requests are matched in order from the `web_dev_config.yaml` file. + +#### Basic string proxy + +Use the `prefix` field for simple path prefix matching! + +```yaml +#web_dev_config.yaml +server: + proxy: + - target: "http://localhost:5000/" # Base URL of your backend + prefix: "/users/" # Path + - target: "http://localhost:3000/" + prefix: "/data/" + replace: "/report/" # Replacement of path in redirected URL (optional) + - target: "http://localhost:4000/" + prefix: "/products/" + replace: "" +``` + +**Explanation:** + +* A request to `/users/names` will be forwarded to `http://localhost:5000/users/names`. +* A request to `/data/2023/` will be forwarded to `http://localhost:4000/report/2023` because `replace: “/report/”` replaces the `/data/` prefix +* A request to `/products/item/123` will be forwarded to `http://localhost:4000/item/123`. `replace: ""` removes the `/products/` prefix by replacing it with an empty string + +#### Advanced regex proxy + +You can also use the `regex` field for more flexible and complex matching! + +```yaml +#web_dev_config.yaml +server: + proxy: + - target: "http://localhost:5000/" + regex: "/users/(\d+)/$" # Path matches requests like /users/123/ + - target: "http://localhost:4000/" + regex: "^/api/(v\d+)/(.*)" # Matches requests like /api/v1/users + replace: "/$2?apiVersion=$1" # Allows capture groups (optional) +``` + +**Explanation:** + +* A request to `/users/123/` matches the first rule exactly, so it will be forwarded to `http://localhost:5000/users/123/` +* A request to `/api/v1/users/profile/` starts with the second rule path, so it will be forwarded to `http://localhost:4000/users/profile/?apiVersion=v1` + +## Configuration precedence + +Remember the order of precedence for settings: + +1. **Command-line arguments** (such as `--web-hostname`, `--web-port`) +2. **`web_dev_config.yaml` settings** +3. **Built-in default values** \ No newline at end of file From 04a5e7bc09029d9709d7526230e8068470da1ba1 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:40:25 -0700 Subject: [PATCH 02/12] Update src/content/platform-integration/web/web-dev-config-file.md Break at 80 chars or less (actually, we prefer semantic line breaks). --- .../platform-integration/web/web-dev-config-file.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index b44d1ebe98..ce0d4d0baf 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -7,7 +7,14 @@ short-title: Web development configuration # Set up a web development configuration file **By Sydney Bao** -Flutter web includes a development server that defaults to serving your application in the `localhost` domain via HTTP on a randomly assigned port. While command-line arguments offer a quick way to modify the server’s behavior, this document focuses on a more structured approach: defining your server's behavior through a centralized `web_dev_config.yaml` file. This configuration file allows you to customize server settings---host, port, HTTPS settings, and proxy rules---ensuring a consistent development environment. +Flutter web includes a development server that defaults to +serving your application in the `localhost` domain using HTTP +on a randomly assigned port. While command-line arguments offer +a quick way to modify the server’s behavior, +this document focuses on a more structured approach: +defining your server's behavior through a centralized `web_dev_config.yaml` file. +This configuration file allows you to customize server settings&emdash;host, port, HTTPS settings, +and proxy rules&emdash;ensuring a consistent development environment. ## Create a configuration file From ba2182051b653a50effb613adb70eabafb074a7b Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:40:41 -0700 Subject: [PATCH 03/12] Update src/content/platform-integration/web/web-dev-config-file.md Ditto --- src/content/platform-integration/web/web-dev-config-file.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index ce0d4d0baf..845f4f0b8d 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -18,7 +18,11 @@ and proxy rules&emdash;ensuring a consistent development environment. ## Create a configuration file -Add a `web_dev_config.yaml` file in the root directory of your Flutter project. If you haven’t set up a Flutter project, visit [Building a web application with Flutter](https://docs.flutter.dev/platform-integration/web/building) to get started. +Add a `web_dev_config.yaml` file to the root directory of your Flutter project. +If you haven’t set up a Flutter project, +visit [Building a web application with Flutter][] to get started. + +[Building a web application with Flutter]: /platform-integration/web/building ## Add configuration settings From c19a59abbaf96055897777c82b08670470be9688 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:41:17 -0700 Subject: [PATCH 04/12] Update src/content/platform-integration/web/web-dev-config-file.md Avoiding the exclamation points. We are typically more subdued (and humble) than that. ;) --- src/content/platform-integration/web/web-dev-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index 845f4f0b8d..ce3ce50fd9 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -28,7 +28,7 @@ visit [Building a web application with Flutter][] to get started. ### Basic server configuration -You can define the host, port, and HTTPS settings for your development server! +You can define the host, port, and HTTPS settings for your development server. ```yaml #web_dev_config.yaml From 398c1baa97ff8bccd6ef91124e3990fba8c2a078 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:41:30 -0700 Subject: [PATCH 05/12] Update src/content/platform-integration/web/web-dev-config-file.md Ditto --- src/content/platform-integration/web/web-dev-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index ce3ce50fd9..b7a0702eda 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -42,7 +42,7 @@ server: ### Custom headers -You can also inject custom HTTP headers into the development server’s responses! +You can also inject custom HTTP headers into the development server’s responses. ```yaml #web_dev_config.yaml From aa9244526473c3ac2c7c097964ea3b02c7e40fa6 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:41:42 -0700 Subject: [PATCH 06/12] Update src/content/platform-integration/web/web-dev-config-file.md Ditto --- src/content/platform-integration/web/web-dev-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index b7a0702eda..dee2bf3129 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -60,7 +60,7 @@ Requests are matched in order from the `web_dev_config.yaml` file. #### Basic string proxy -Use the `prefix` field for simple path prefix matching! +Use the `prefix` field for simple path prefix matching. ```yaml #web_dev_config.yaml From 3bcc6491c28e92cd7ef6b8bf5a42cd225b42266e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:42:26 -0700 Subject: [PATCH 07/12] Update src/content/platform-integration/web/web-dev-config-file.md Breaking up long lines _and_ changing verbs to current tense. --- .../platform-integration/web/web-dev-config-file.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index dee2bf3129..ec4d4023a2 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -78,9 +78,11 @@ server: **Explanation:** -* A request to `/users/names` will be forwarded to `http://localhost:5000/users/names`. -* A request to `/data/2023/` will be forwarded to `http://localhost:4000/report/2023` because `replace: “/report/”` replaces the `/data/` prefix -* A request to `/products/item/123` will be forwarded to `http://localhost:4000/item/123`. `replace: ""` removes the `/products/` prefix by replacing it with an empty string +* A request to `/users/names` is forwarded to `http://localhost:5000/users/names`. +* A request to `/data/2023/` is forwarded to `http://localhost:4000/report/2023` + because `replace: “/report/”` replaces the `/data/` prefix. +* A request to `/products/item/123` is forwarded to `http://localhost:4000/item/123` + because`replace: ""` removes the `/products/` prefix by replacing it with an empty string. #### Advanced regex proxy From 1986419b9780a49a8cb99cd9fefd80e12dce6d9e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:42:40 -0700 Subject: [PATCH 08/12] Update src/content/platform-integration/web/web-dev-config-file.md --- src/content/platform-integration/web/web-dev-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index ec4d4023a2..76d0da65ea 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -86,7 +86,7 @@ server: #### Advanced regex proxy -You can also use the `regex` field for more flexible and complex matching! +You can also use the `regex` field for more flexible and complex matching. ```yaml #web_dev_config.yaml From e00eedd29029ed8fd42dd4230353d5813e0e22f2 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 23 Jul 2025 14:43:22 -0700 Subject: [PATCH 09/12] Update src/content/platform-integration/web/web-dev-config-file.md Making the list parallel. Actually, I should have removed that comma after path in the second item. --- src/content/platform-integration/web/web-dev-config-file.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index 76d0da65ea..01a57e8ca6 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -101,8 +101,10 @@ server: **Explanation:** -* A request to `/users/123/` matches the first rule exactly, so it will be forwarded to `http://localhost:5000/users/123/` -* A request to `/api/v1/users/profile/` starts with the second rule path, so it will be forwarded to `http://localhost:4000/users/profile/?apiVersion=v1` +* A request to `/users/123/` matches the first rule exactly, + so it is forwarded to `http://localhost:5000/users/123/`. +* A request to `/api/v1/users/profile/` starts with the second rule path, + so it is forwarded to `http://localhost:4000/users/profile/?apiVersion=v1`. ## Configuration precedence From f895e25a20b004ae8ae110824734e9c29cd87862 Mon Sep 17 00:00:00 2001 From: Sydney Bao Date: Thu, 24 Jul 2025 16:05:31 -0700 Subject: [PATCH 10/12] add to index --- src/content/platform-integration/web/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index b446c6c418..c2a3d3fdab 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -68,8 +68,9 @@ The following resources can help you get started: * To add web support to an existing app, or to create a new app that includes web support, see [Building a web application with Flutter][]. +* To configure web development server settings in a centralized file, see [Set up a web development configuration file][]. * To learn about Flutter's different web renderers (CanvasKit and Skwasm), see - [Web renderers][] + [Web renderers][]. * To learn how to create a responsive Flutter app, see [Creating responsive apps][]. * To view commonly asked questions and answers, see the @@ -83,6 +84,7 @@ The following resources can help you get started: * You can chat and ask web-related questions on the **#help** channel on [Discord][]. +[Set up a web development configuration file]: /platform-integration/web/web-dev-config-file [Building a web application with Flutter]: /platform-integration/web/building [Creating responsive apps]: /ui/adaptive-responsive [Discord]: https://discordapp.com/invite/yeZ6s7k From 63615dfc0daa375c9a7c5071f748bf4c8bb21f33 Mon Sep 17 00:00:00 2001 From: Sydney Bao Date: Thu, 24 Jul 2025 16:16:31 -0700 Subject: [PATCH 11/12] update index --- src/content/platform-integration/web/index.md | 2 +- src/content/platform-integration/web/web-dev-config-file.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index c2a3d3fdab..3e88829666 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -84,8 +84,8 @@ The following resources can help you get started: * You can chat and ask web-related questions on the **#help** channel on [Discord][]. -[Set up a web development configuration file]: /platform-integration/web/web-dev-config-file [Building a web application with Flutter]: /platform-integration/web/building +[Set up a web development configuration file]: /platform-integration/web/web-dev-config-file [Creating responsive apps]: /ui/adaptive-responsive [Discord]: https://discordapp.com/invite/yeZ6s7k [file an issue]: https://goo.gle/flutter_web_issue diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index 01a57e8ca6..25e2b24dec 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -103,7 +103,7 @@ server: * A request to `/users/123/` matches the first rule exactly, so it is forwarded to `http://localhost:5000/users/123/`. -* A request to `/api/v1/users/profile/` starts with the second rule path, +* A request to `/api/v1/users/profile/` starts with the second rule path so it is forwarded to `http://localhost:4000/users/profile/?apiVersion=v1`. ## Configuration precedence From 069b587200643f84b113b819cc3a8abde4867d49 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Wed, 13 Aug 2025 23:04:12 +0800 Subject: [PATCH 12/12] Minor formatting clean up --- .../web/web-dev-config-file.md | 79 ++++++++++--------- 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/src/content/platform-integration/web/web-dev-config-file.md b/src/content/platform-integration/web/web-dev-config-file.md index 25e2b24dec..7ee0304366 100644 --- a/src/content/platform-integration/web/web-dev-config-file.md +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -1,25 +1,27 @@ --- title: Set up a web development configuration file -description: Centralize web development settings including a development proxy short-title: Web development configuration +description: >- + Centralize web development settings including a development proxy --- # Set up a web development configuration file -**By Sydney Bao** +**By Sydney Bao** Flutter web includes a development server that defaults to serving your application in the `localhost` domain using HTTP on a randomly assigned port. While command-line arguments offer -a quick way to modify the server’s behavior, +a quick way to modify the server's behavior, this document focuses on a more structured approach: defining your server's behavior through a centralized `web_dev_config.yaml` file. -This configuration file allows you to customize server settings&emdash;host, port, HTTPS settings, -and proxy rules&emdash;ensuring a consistent development environment. +This configuration file allows you to +customize server settings&emdash;host, port, HTTPS settings, and +proxy rules&emdash;ensuring a consistent development environment. ## Create a configuration file Add a `web_dev_config.yaml` file to the root directory of your Flutter project. -If you haven’t set up a Flutter project, +If you haven't set up a Flutter project, visit [Building a web application with Flutter][] to get started. [Building a web application with Flutter]: /platform-integration/web/building @@ -30,24 +32,22 @@ visit [Building a web application with Flutter][] to get started. You can define the host, port, and HTTPS settings for your development server. -```yaml -#web_dev_config.yaml +```yaml title="web_dev_config.yaml" server: - host: "0.0.0.0" # Defines the binding address - port: 8080 # Specifies the port for the development server + host: "0.0.0.0" # Defines the binding address + port: 8080 # Specifies the port for the development server https: - cert-path: "/path/to/cert.pem" # Path to your TLS certificate + cert-path: "/path/to/cert.pem" # Path to your TLS certificate cert-key-path: "/path/to/key.pem" # Path to TLS certificate key ``` ### Custom headers -You can also inject custom HTTP headers into the development server’s responses. +You can also inject custom HTTP headers into the development server's responses. -```yaml -#web_dev_config.yaml +```yaml title="web_dev_config.yaml" server: - headers: + headers: - name: "X-Custom-Header" # Name of the HTTP header value: "MyValue" # Value of the HTTP header - name: "Cache-Control" @@ -56,16 +56,15 @@ server: ### Proxy configuration -Requests are matched in order from the `web_dev_config.yaml` file. +Requests are matched in order from the `web_dev_config.yaml` file. #### Basic string proxy Use the `prefix` field for simple path prefix matching. -```yaml -#web_dev_config.yaml -server: - proxy: +```yaml title="web_dev_config.yaml" +server: + proxy: - target: "http://localhost:5000/" # Base URL of your backend prefix: "/users/" # Path - target: "http://localhost:3000/" @@ -73,43 +72,45 @@ server: replace: "/report/" # Replacement of path in redirected URL (optional) - target: "http://localhost:4000/" prefix: "/products/" - replace: "" + replace: "" ``` -**Explanation:** +**Explanation:** -* A request to `/users/names` is forwarded to `http://localhost:5000/users/names`. -* A request to `/data/2023/` is forwarded to `http://localhost:4000/report/2023` - because `replace: “/report/”` replaces the `/data/` prefix. -* A request to `/products/item/123` is forwarded to `http://localhost:4000/item/123` - because`replace: ""` removes the `/products/` prefix by replacing it with an empty string. +* A request to `/users/names` is + forwarded to `http://localhost:5000/users/names`. +* A request to `/data/2023/` is + forwarded to `http://localhost:4000/report/2023` + because `replace: “/report/”` replaces the `/data/` prefix. +* A request to `/products/item/123` is + forwarded to `http://localhost:4000/item/123` because `replace: ""` + removes the `/products/` prefix by replacing it with an empty string. #### Advanced regex proxy You can also use the `regex` field for more flexible and complex matching. -```yaml -#web_dev_config.yaml +```yaml title="web_dev_config.yaml" server: proxy: - - target: "http://localhost:5000/" - regex: "/users/(\d+)/$" # Path matches requests like /users/123/ + - target: "http://localhost:5000/" + regex: "/users/(\d+)/$" # Path matches requests like /users/123/ - target: "http://localhost:4000/" regex: "^/api/(v\d+)/(.*)" # Matches requests like /api/v1/users replace: "/$2?apiVersion=$1" # Allows capture groups (optional) ``` -**Explanation:** +**Explanation:** -* A request to `/users/123/` matches the first rule exactly, - so it is forwarded to `http://localhost:5000/users/123/`. -* A request to `/api/v1/users/profile/` starts with the second rule path - so it is forwarded to `http://localhost:4000/users/profile/?apiVersion=v1`. +* A request to `/users/123/` matches the first rule exactly, + so it is forwarded to `http://localhost:5000/users/123/`. +* A request to `/api/v1/users/profile/` starts with the second rule path + so it is forwarded to `http://localhost:4000/users/profile/?apiVersion=v1`. ## Configuration precedence Remember the order of precedence for settings: -1. **Command-line arguments** (such as `--web-hostname`, `--web-port`) -2. **`web_dev_config.yaml` settings** -3. **Built-in default values** \ No newline at end of file +1. **Command-line arguments** (such as `--web-hostname`, `--web-port`) +2. **`web_dev_config.yaml` settings** +3. **Built-in default values**