From 5d9b7792757997b0150be8a70087745e982fb4e3 Mon Sep 17 00:00:00 2001 From: Dustin Pauze Date: Thu, 19 Feb 2026 11:32:17 -0500 Subject: [PATCH] FEDX-1146: co-authored by Cursor --- README.md | 107 ++++++++++++++++++++---------------------------------- 1 file changed, 40 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 2896adf..9b13740 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,71 @@ -A simple HTTP proxy for [webdev's serve command][webdev-serve] that adds support -for rewriting certain requests, namely rewriting 404s to instead serve the root -index (`/`). +[Reference Pills] +[![Slack Channel](https://img.shields.io/badge/Support_Channel-Slack-purple)](https://slack.com/app_redirect?channel=support-frontend-dx) +[![Maintainer](https://img.shields.io/badge/maintainer-FEDX-silver)](https://wiki.atl.workiva.net/display/FEF/Frontend+Dev+Experience) +[![Documentation](https://img.shields.io/badge/Additional_Documentation-blue)](https://frontend.workiva.dev) -## Requirements +# webdev_proxy -The latest release of `webdev_proxy` requires the following: +`webdev_proxy` is a lightweight HTTP proxy for `webdev serve` that helps web apps using HTML5 routing. It rewrites 404 responses to the root `index.html`, so client-side routes keep working during local development. This tool is intended for frontend developers working with Dart/webdev-based applications. -- Dart SDK `2.11` or later -- `webdev` globally activated at a version in the `>=1.0.1 <3.0.0` range - - Be sure to follow the [installation instructions for webdev][webdev-install] +## Quick Start -## Installation +### Prerequisites -`webdev_proxy` is intended to be ["activated"][pub-global-activate] rather than -installed as a package dependency. +- Dart SDK `>=2.19.0 <3.0.0` +- `webdev` globally activated in your Dart environment + +### Installation ```bash -$ dart pub global activate webdev_proxy +dart pub global activate webdev_proxy ``` -Learn more about activating and using packages [here][pub-global]. - -## Usage +### Usage -`webdev_proxy` supports one command: `serve` - -### `webdev_proxy serve` +Run the proxy in front of `webdev serve`: +```bash +webdev_proxy serve ``` -Run `webdev serve` (a local web development server) behind a proxy that supports HTML5 routing by rewriting not-found requests to index.html. - -Usage: webdev_proxy serve [-- [webdev serve arguments]] --h, --help Print this usage information. - --[no-]rewrite-404s Rewrite every request that returns a 404 to /index.html - (defaults to on) - -Run "webdev_proxy help" to see global options. - -You may use any of the following options supported by `webdev serve` by passing them after the `--` separator. - -webdev serve --help: -==================== -Run a local web development server and a file system watcher that rebuilds on changes. +Pass any supported `webdev serve` options after `--`: -Usage: webdev serve [arguments] [[:]]... --h, --help Print this usage information. --o, --output A directory to write the result of a build to. Or a mapping from a top-level directory in the package to the directory to write a filtered build output to. For example - "web:deploy". - A value of "NONE" indicates that no "--output" value should be passed to `build_runner`. - (defaults to "NONE") - --r, --[no-]release Build with release mode defaults for builders. - --[no-]build-web-compilers If a dependency on `build_web_compilers` is required to run. - (defaults to on) +```bash +webdev_proxy serve -- --auto=refresh +``` --v, --verbose Enables verbose logging. - --auto Automatically performs an action after each build: +## Documentation - restart: Reload modules and re-invoke main (loses current state) - refresh: Performs a full page refresh. - [restart, refresh] +- Package repository: https://github.com/Workiva/webdev_proxy +- Dart pub global activation docs: https://dart.dev/tools/pub/cmd/pub-global#activating-a-package - --chrome-debug-port Specify which port the Chrome debugger is listening on. If used with launch-in-chrome Chrome will be started with the debugger listening on this port. - --[no-]debug Enable the launching of DevTools (Alt + D). Must use with either --launch-in-chrome or --chrome-debug-port. - --hostname Specify the hostname to serve on. - (defaults to "localhost") +## Development - --[no-]launch-in-chrome Automatically launches your application in Chrome with the debug port open. Use chrome-debug-port to specify a specific port to attach to an already running chrome instance - instead. +### Setup - --log-requests Enables logging for each request to the server. +Install dependencies and verify the CLI help output: -Run "webdev help" to see global options. +```bash +dart pub get +dart run bin/webdev_proxy.dart --help ``` -Note that you can configure the underlying `webdev serve` process by passing any -of its supported command-line arguments after the `--` separator. +### Testing -#### Examples - -To run the default server and proxy: +Run the test suite: ```bash -$ webdev_proxy serve +dart test ``` -To pass arguments to `webdev serve`, e.g. to enable auto-refresh: +### Building + +Build a standalone executable: ```bash -$ webdev_proxy serve -- --auto=refresh +dart compile exe bin/webdev_proxy.dart -o webdev_proxy ``` -[pub-global]: https://dart.dev/tools/pub/cmd/pub-global -[pub-global-activate]: https://dart.dev/tools/pub/cmd/pub-global#activating-a-package -[webdev-install]: https://github.com/dart-lang/webdev#requirements -[webdev-serve]: https://github.com/dart-lang/webdev/tree/master/webdev#webdev-serve +## Support + +For help or feature discussions, use the Frontend DX support Slack channel: https://slack.com/app_redirect?channel=support-frontend-dx. For maintainer ownership details, see the FEDX wiki page: https://wiki.atl.workiva.net/display/FEF/Frontend+Dev+Experience.