{"id":21995052,"url":"https://github.com/redhataccess/spandx","last_synced_at":"2025-04-06T14:11:04.260Z","repository":{"id":24872819,"uuid":"102500063","full_name":"redhataccess/spandx","owner":"redhataccess","description":"Develop locally, proxy to prod, browser-sync, and process ESI tags.","archived":false,"fork":false,"pushed_at":"2025-03-12T18:30:50.000Z","size":3245,"stargazers_count":22,"open_issues_count":26,"forks_count":19,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-30T13:08:17.386Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhataccess.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-05T15:42:21.000Z","updated_at":"2023-06-27T20:45:02.000Z","dependencies_parsed_at":"2024-04-26T17:43:03.679Z","dependency_job_id":"bdace3b4-c724-417d-b293-855e8d20b8a8","html_url":"https://github.com/redhataccess/spandx","commit_stats":{"total_commits":380,"total_committers":11,"mean_commits":34.54545454545455,"dds":0.4605263157894737,"last_synced_commit":"dc390716853e38d0d9dbb2508be3479f02e19007"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhataccess%2Fspandx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhataccess%2Fspandx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhataccess%2Fspandx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhataccess%2Fspandx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhataccess","download_url":"https://codeload.github.com/redhataccess/spandx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246944384,"owners_count":20858773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T21:12:11.170Z","updated_at":"2025-04-06T14:11:04.233Z","avatar_url":"https://github.com/redhataccess.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![spandx logo](./spandx-logo.png)\n\n[![Build Status][build-img]][build]\n\n# What is spandx?\n\nspandx is an **HTTP switchboard**.  With it, you can weave together pieces of a large, complex website by choosing which resources should come from your local system and which should come from a remote environment.\n\nFor example, you could point spandx at your production site, but route `/static/js` to a local directory, which allows you to test your local JS against the production environment.  Code in production, it's fun.\n\nMore technically, spandx is a flexible, configuration-based reverse proxy for local development.\n\n# Quick-start\n\n*(Note: if you're a developer on the Customer Portal, please use [this guide][rh-quickstart])*\n\nWhile I recommend [local install][local-dep], if you want to quickly take spandx for a whirl, the fastest way to get started is by installing spandx as a global package.\n\n    npm install -g spandx\n\nGenerate a sample configuration file:\n\n    spandx init \u003e spandx.config.js\n\nLaunch!\n\n    spandx\n\n---\n\n# Table of Contents\n\n\u003c!-- toc --\u003e\n\n- [Commands](#commands)\n  * [spandx](#spandx)\n  * [init](#init)\n- [Configuration](#configuration)\n  * [spandx.config.js](#spandxconfigjs)\n  * [Routes](#routes)\n    + [Routing to a local directory](#routing-to-a-local-directory)\n    + [Routing to a server](#routing-to-a-server)\n      - [Multi-host routing](#multi-host-routing)\n      - [Path rewriting](#path-rewriting)\n      - [single mode](#single-mode)\n  * [Setting up the proxy object](#setting-up-the-proxy-object)\n  * [Overriding Browsersync options](#overriding-browsersync-options)\n    + [Enabling HTTPS](#enabling-https)\n- [spandx as a local dependency](#spandx-as-a-local-dependency)\n- [Contributing](#contributing)\n  * [Commit messages](#commit-messages)\n  * [Running specific tests](#running-specific-tests)\n- [Known issues](#known-issues)\n  * [cURLing spandx](#curling-spandx)\n    + [Body URL rewriting](#body-url-rewriting)\n    + [single mode URL rewriting](#single-mode-url-rewriting)\n- [Alternatives](#alternatives)\n\n\u003c!-- tocstop --\u003e\n\n# Commands\n\n## spandx\n\nTo launch spandx, simply run `spandx`.  If a `spandx.config.js` file exists in the current directory, it will be used.\n\nOption  | Description | Example\n--- | --- | ---\n`-c`, `--config` | Specify an alternate config file.  Config files are JS by default (to enable commenting), but JSON is also accepted. | `spandx -c ./configs/spandx.json`\n`-v`, `--version` | Print the current version of spandx. | `spandx -v`\n\n## init\n\nGenerate a configuration file.  When invoked with no arguments, it prints a barebones config file.  Redirect to a file (this could be improved by writing the file automatically).\n\n```\nspandx init \u003e spandx.config.js\n```\n\n# Configuration\n\nAfter `spandx init` has generated a configuration file for you, there are many ways you can tweak it.\n\n## spandx.config.js\n\nHere are the configuration options accepted by the config file. \n\nOption | Description | Type\n---|---|---\n`host` | The hostname you wish to use to access spandx. Usually \"localhost\", or a [multi-host](#multi-host-routing) object. | string or object\n`port` | The port for spandx to listen on, or \"auto\". | number or \"auto\"\n`open` | Whether to open a browser tab when spandx is launched. | boolean\n`startPath` | The URL path to open, if `open` is true. ex: `\"/site\"`. | string\n`verbose` | Display English summary of configuration settings and display Browsersync logs, or not. | boolean\n`silent` | Print nothing to stdout. | boolean\n`routes` | Define where to send requests for any number of URL paths, best explained in [routes by example](#routes). | object\n`bs` | A [Browsersync config object][bs-options], in case you need to further customize spandx's Browsersync instance. | object\n`portalChrome` | Settings related to Portal Chrome, see [Portal Chrome settings][portal-chrome-settings]. | object\n`esi` | Set to `true` to enable processing [ESI][esi] tags, or pass in a [nodesi][nodesi] config object. | boolean or object\n`proxy` | Define a proxy host and a URL regex pattern for target URLs that should be proxied. | object\n\n## Routes\n\nRoutes are the core of spandx's flexibility.  They allow you to define where to pull assets at any given URL path.\n\nRoute all requests to palebluepixel.org (a perfect reverse proxy), *unless* the request falls under `/theme`, in which case look for files in `~/projects/pbp/theme`.\n\n    routes: {\n        \"/theme\" : \"~/projects/pbp/theme/\",\n        \"/\"      : { host: \"https://palebluepixel.org/\" },\n    },\n\nHere's how this configuration would play out.\n\n  1. visit localhost:1337 and you see what looks like palebluepixel.org\n  2. one exception, the page includes `/theme/site.css`\n  3. because it falls under the `/theme` route, spandx fetches `~/projects/pbp/theme/site.css` instead of `palebluepixel.org/theme/site.css`\n\nThis effectively _overlays_ a local directory of static files on top of a remote server.  In other words... test in production!\n\nIn addition, because `~/projects/pbp/theme` is a local directory, changes to files inside it will trigger a Browsersync refresh.\n\n### Routing to a local directory\n\nTo route to a local directory, the destination should be a string.  The directory path can be absolute or relative.  If relative, it's resolved relative to the spandx.config.js file.\n\n```\nroutes: {\n    \"/incoming\": \"./destination\"\n}\n```\n\n### Routing to a server\n\nTo route to a server, the destination should be an object with a `host` property.\n\n```js\nroutes: {\n    \"/incoming\": {\n      host: \"http://localhost:8080\"\n    }\n}\n```\n\nIn this form, requests to `/incoming` will route to `http://localhost:8080/incoming`.  If you would rather route to a different path (such as `http://localhost:8080`), you can specify a `path` property as follows.\n\n#### Multi-host routing\n\nMany projects have multiple remote webservers, for example a dev server, qa, staging, and production.  To simplify dealing with multiple remotes, spandx offers multi-host routing, whether the local hostname determines which remote host to proxy to.  Here's an example config.\n\n\n```js\nmodule.exports = {\n    host: {\n +---\u003c  dev: \"dev-local.foo.com\",\n |      prod: \"prod-local.foo.com\"\n |  },\n |  routes: {\n |      \"/\": {\n |          host: {\n +-----------\u003e  dev: \"http://dev.foo.com\",\n                prod: \"http://www.foo.com\"\n            }\n        }\n    }\n};\n```\n\nIn this case, dev-local.foo.com and prod-local.foo.com should be entered in `/etc/hosts`, pointing to `127.0.0.1`.  Then, when spandx is visited at dev-local.foo.com, spandx knows it's the \"dev\" host and proxies to dev.foo.com.  The names \"dev\" and \"prod\" can be any names you choose.  See the [examples](examples) dir for a working example.\n\n\n#### Path rewriting\n\n```js\nroutes: {\n    \"/my-app\": {\n      host: \"http://localhost:8080\",\n      path: \"/\"\n    }\n}\n```\n\nWith this path setting, requests to `/my-app` will route to `http://localhost:8080/`.  This is particularly useful when using a local development server (like webpack-dev-server) where your app lives at `/`.\n\n#### single mode\n\nWhen a route has `single: true`, spandx will send all requests under that route to a single index.html file (except requests for assets).\n\nThis is intended to be used with [`pushState`][pushstate] and enables hash-free user-friendly URLs for single-page apps.\n\n```js\nroutes: {\n    \"/my-app\": {\n      host: \"http://localhost:8080\",\n      single: true\n    }\n}\n```\n\nWith this config, a request to `/my-app/users/active` would be routed to `http://localhost:8080/my-app/index.html`.\n\n`single` can also be combined with `path`.\n\n```js\nroutes: {\n    \"/my-app\": {\n      host: \"http://localhost:8080\",\n      path: \"/\",\n      single: true\n    }\n}\n```\n\nHere, a request to `/my-app/users/active` would be routed to `http://localhost:8080/`.\n\n## Setting up the proxy object\n\nIf you're developing an app that needs to connect to a proxy, use the proxy object to define the proxy host and define a URL regex pattern for request that should go through the proxy.\n\n```js\nproxy: {\n    host: \"http://someproxy.com:1234\",\n    pattern: \"^https:\\/\\/(.*?).someurl.com\"\n}\n```\n\nHere, when a URL like `https://api.qa.someurl.com` is requested, it would be routed through the proxy.\n\n## Overriding Browsersync options\n\nInternally, spandx uses Browsersync to power some features like live-reloading.  Custom [Browsersync options][bs-options] can be embedded in your spandx.config.js file under the `bs` property.\n\nFor example, let's enable HTTPS.\n\n### Enabling HTTPS\n\nYou can enable HTTPS by \n\n```js\nmodule.exports = {\n    bs: {\n        https: true,\n    }\n};\n```\n\nFor extra customization (like providing your own certs), see [Browsersync's HTTPS options][bs-https].\n\n# spandx as a local dependency\n\nThe quick-start has you install spandx as a global package for simplicity, but installing it locally per-project is a better approach in many ways.\n\nGo to your project, install spandx as a dev dependency, and create a config file:\n\n    cd $YOUR_PROJECT\n    npm install --save-dev spandx\n    npx spandx init \u003e spandx.config.js\n\nModify `spandx.config.js` to reflect the needs of your application.\n\nThen edit your `package.json` and add a `start` script which launches spandx.\n\n```json\n    \"scripts\": {\n        \"start\": \"spandx\"\n    }\n```\n\nNow you and your fellow contributors can run `yarn start` without having to install or even understand spandx!\n\n# Contributing\n\nContributions are very welcome!  There's not much here yet, but when there's enough content it can be split out into a dedicated CONTRIBUTING.md.\n\n## Commit messages\n\nStarting with spandx v2.0.0, one goal is to adhere to the [Conventional Commits][conv-comm] style of writing commit messages.  The rewards of doing so are automating semantic version bumps and CHANGELOG updates.  For now, the commit style will be used and later on, the tooling ([conventional-changelog-cli][conv-cli] perhaps) will be added.\n\n## Running specific tests\n\nWhen writing a test, or debugging a failing test, you may want to run *only* that test instead of the entire suite.  To do that, you can filter by the name of the test.  Just be specific enough to target only the test (or tests) you want to run.\n\nFor example, to run the test named \"should reject invalid multi-host configs\":\n\n    yarn test -- --filter=\"invalid multi\"\n\n# Known issues\n\n## cURLing spandx\n\nWhen curling spandx, if you are requesting an HTML document, it's important to include an appropriate `Accept` header.  There are two spandx features, described below, that will not work without that header.\n\n### Body URL rewriting\n\nThe URL-rewriting feature is powered by browserSync's rewriteRules.  However, Browsersync will only perform the rewrites if `text/html` is present in the request's `Accept` header.  Web browsers include it by default, but if you're using [cURL][curl], you'll need to add that header in order for URLs to be rewritten.\n\nFor example:\n\n    curl -H 'Accept: text/html' localhost:1337\n\n### single mode URL rewriting\n\nJust like body URL rewriting, the URL rewrite associated with the [`single`][single-mode] also needs the incoming `Accept` header to include `text/html`.\n\nAll other spandx features work with or without `text/html` in the `Accept` header.\n\n# Alternatives\n\nIf spandx doesn't fit, here are a few other tools that offer similar features.\n\n - [devd][devd], a local development server with a focus on flexible reverse proxying, much like spandx.  Written in Go.\n - [http-server][http-server], a simple command-line HTTP server.  The `--proxy` flag provides a remote fallback for requests that can't be resolved locally.  Written in JS.\n - [dprox][dprox], a declarative reverse proxy for local development.  Similar configuration philosophy to spandx.'\n - [traefik][traefik]\n\n\n\n[curl]: https://curl.haxx.se/\n[npm]: https://www.npmjs.com/package/spandx\n[build-img]: https://travis-ci.org/redhataccess/spandx.png?branch=master\n[build]: https://travis-ci.org/redhataccess/spandx\n[bs-options]: https://browsersync.io/docs/options\n[devd]: https://github.com/cortesi/devd\n[http-server]: https://github.com/http-party/http-server#readme\n[dprox]: https://github.com/FND/dprox\n[single-mode]: #single-mode\n[local-dep]: #spandx-as-a-local-dependency\n[bs-https]: https://www.browsersync.io/docs/options#option-https\n[rh-quickstart]: ./RH.md\n[portal-chrome-settings]: ./RH.md#portal-chrome-settings\n[pushstate]: https://developer.mozilla.org/en-US/docs/Web/API/History_API\n[esi]: https://en.wikipedia.org/wiki/Edge_Side_Includes\n[nodesi]: https://github.com/Schibsted-Tech-Polska/nodesi\n[conv-comm]: https://www.conventionalcommits.org/#summary\n[conv-cli]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli\n[traefik]: https://github.com/traefik/traefik\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhataccess%2Fspandx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhataccess%2Fspandx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhataccess%2Fspandx/lists"}