network-overrides

Via the combination of a CLI and a browser extension, define sets of browser-side redirects (overrides) programmatically from the command line.

It was designed to allow one to develop web client-side apps on top of an external environment (ex: test or production) using assets served from one (or multiple) local dev-server(s).

Additionally, by having the command line as a source of truth, one can ensure that a set of overrides are only in place while the related process is running (ex: dev-server).

Getting started

1. Install npm package locally:

npm i network-overrides

2. Bootstrap a local dev-server, wrapped with overrides:

npx network-overrides wrap-command 'npx webpack serve' my-first-override '[{"from":"https://live-cdn\\.com/(.*)","to":"http://localhost:8080/$1"}]' --ensure-backend

What does that command do?

1. Ensure that the Network Overrides shared backend is running, which in turn will transmit the current overrides to the browser extension when necessary
2. Add a single override which redirects assets from https://live-cdn.com/ to the corresponding path under http://localhost:8080/. It belongs to an override set called my-first-override
3. Run npx webpack serve which will bootstrap the local webpack-dev-server
4. Later, upon exiting, remove the override under my-first-override

See CLI commands for more details on the available API.

3. Install the companion extension:

• Chrome:
  • From Chrome's webstore
  • Manually:
    1. Download the network-overrides-<version>.crx from the latest release
    2. Open chrome://extensions/, enable Developer Mode and drag-and-drop the downloaded extension over the extensions page.

4. Enable the current overrides on the browser-side

Click the extension's icon and then the Connect button inside the extension's popover.

Override

An override is described by a couple of properties:

• from: RegExp string that is used as a matching pattern for request urls, optionally defining the capture groups to be used in replacements with to
• to: Replacement string, able to support the typical patterns.

Essentially, the override is used within the extension as follows:

const pattern = new RegExp(override.from);

if(interceptedRequestUrl.match(pattern)){
  const redirectUrl = interceptedRequestUrl.replace(pattern, override.to);
  ...
}

API

See CLI commands.

Components

network-overrides node package

The network-overrides node package is the core API in terms of controlling the active overrides.

In the middle of it all we have a shared backend process (typically running in the background) that:

1. keeps in memory the list of current overrides
2. is a REST server that exposes endpoints for listing, adding and removing overrides
3. is a websocket server that allows the browser extension to be in sync with the current overrides

The CLI then serves as the API for that shared backend process, providing several commands that deal with bootstrapping the latter and adding/removing overrides.

Network Overrides browser extension

The browser extension is responsible for:

1. Allowing the user connect/disconnect with the shared backend's websockets
2. Display the current sets of overrides
3. Using the webRequest API intercept requests and conditionally redirect them based on the overrides in place

Next steps

• add network-overrides stop-backend command
• automatically stop shared backend when running in a background process and becomes idle
• add tests
• convert to TypeScript