diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index b446c6c418..3e88829666 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 @@ -84,6 +85,7 @@ The following resources can help you get started: **#help** channel on [Discord][]. [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 new file mode 100644 index 0000000000..7ee0304366 --- /dev/null +++ b/src/content/platform-integration/web/web-dev-config-file.md @@ -0,0 +1,116 @@ +--- +title: Set up a web development configuration file +short-title: Web development configuration +description: >- + Centralize web development settings including a development proxy +--- + +# 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 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 + +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 + +### Basic server configuration + +You can define the host, port, and HTTPS settings for your development server. + +```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 + 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 title="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 title="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` 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 title="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 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**