Type definitions
Powered by Typescript
For Typescript users, Proxyflare for Pages comes with type definitions and in-editor documentation.
Configuration
The Configuration type:
export type Configuration = {
global?: {
/**
* Disable Proxyflare without uninstalling it.
*
* @defaultValue `false`
*/
disable?: boolean
/**
* Enable `debug` to attach the following debug headers to Proxyflare responses. Make sure to disable `debug` when you are done configuring Proxyflare.
*
* `x-proxyflare: "running"` signals that Proxyflare is installed
*
* `x-proxyflare-error: string` describes an error if it occured, usually if the provided configuration is incorrect
*
* `x-proxyflare-matched-index: number | "none"` is a zero-indexed route that was matched to the request or "none"
*
* `x-proxyflare-proxied-path: "string"` is the pathname of the proxied request
*
* @defaultValue `false`
*/
debug?: boolean
}
routes: Route[]
}
Route
A Route type:
export type Route = {
/**
* A brief description the purpose of the route
*/
description?: string
from: {
/**
* The [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name#Example) to match against incoming traffic to determine if the route should be proxied by Proxyflare. May be an absolute or wildcard url.
*
* {@link Route.alsoMatchWWWSubdomain | See the `alsoMatchWWWSubdomain` option for additional configuration}
*
* {@link Route.stripFromPath | See the `stripFromPath` option for additional configuration}
*
* @example
* Request: `https://admin.a.com/api`
* from.pattern: `admin.a.com/api/*`
* ✅ MATCH
*
* Request: `https://admin.a.com/api/users`
* from.pattern: `admin.a.com/api/*`
* ✅ MATCH
*
* Request: `https://admin.a.com/api-in-pathname`
* from.pattern: `admin.a.com/api/*`
* ❌ NOT MATCHED
*
* Request: `https://admin.a.com/absolute`
* from.pattern: `admin.a.com/absolute`
* ✅ MATCH
*
* Request: `https://admin.a.com/absolute/subpath`
* from.pattern: `admin.a.com/absolute`
* ❌ NOT MATCHED
*/
pattern: string
/**
* By default, Proxyflare strips the `from.pattern` path from the proxied url. Disable this option to include it.
*
* @defaultValue `true`
*
* @example
* Request: `a.com/api/b`
* from.pattern: `a.com/api/*`
* from.stripFromPath: `true`
* to.url: `b.com`
* -> proxies to `b.com/api/b`
*
* @example
* Request: `a.com/api/b`
* from.pattern: `a.com/api/*`
* from.stripFromPath: `false`
* to.url: `b.com`
* -> proxies to `b.com/api/api/b`
*/
stripFromPath?: boolean
/**
* By default, Proxyflare does not loosely match `www` subdomain and root domain requests. Enable this to loosely match incoming `www` subdomain so that incoming `www` traffic will match root domain routes and vice versa
*
* @defaultValue `false`
*
* @example
* Request: `a.com/loose` or `www.a.com/loose`
* from.alsoMatchWWWSubdomain: `false`
* from.pattern: `a.com/loose`
* to.url: `example.com`
* ❌ NOT MATCHED
*
* @example
* Request: `www.a.com/strict`
* from.alsoMatchWWWSubdomain: `true`
* from.pattern: `a.com/strict`
* to.url: `example.com`
* ✅ BOTH MATCH
*/
alsoMatchWWWSubdomain?: boolean
/**
* By default, Proxyflare ignores request methods when matching requests to a route. To match only specific request methods, enumerate the allowed methods here. Request methods that are not listed will not be matched.
*
* @defaultValue undefined (every methods is matched)
*
* @example
* Request: `POST a.com/b`
* from.pattern: `a.com/b/*`
* from.methods: `["GET"]`
* to.url: `b.com`
* ❌ NOT MATCHED
*/
methods?: Methods[]
}
to: ToURL | ToText | ToR2Bucket
headers?: {
/**
* Request headers to append to proxied requests
*
* @example
* headers.request: `{ "hello-server" : "👋" }`
*/
request?: Record<string, string>
/**
* Response headers to append to proxied responses
*
* @example
* headers.response: `{ "hello-browser" : "👋" }`
*/
response?: Record<string, string>
}
cf?: {
options: IncomingRequestCfProperties | RequestInitCfProperties
}
}
type ToBase = {
/**
* By default, Proxyflare returns the status code of the proxied response. Provide a status code to override this. Status code is additionally used for redirects. To redirect incoming traffic, provide a valid redirect status code.
*
* @defaultValue 200
*
* @example
* Request: `a.com/redirect`
* from.pattern: `a.com/redirect/*`
* to.url: `example.com`
* to.statusCode: 301
* ✅ Permanently redirect traffic to example.com
*/
statusCode?: number
website?: {
/**
* If the `website` configuration is provided, Proxyflare performs website-specific processing on incoming traffic.
* @defaultValue true
*
* `website:true` treats the website like a traditional server-side rendered website (i.e. WordPress).
*
* `website:"spa"` treats the website like a single page app (i.e. React, Vue) that
* has a client side router.
*/
mode?: true | "spa"
/**
* By default, Proxyflare automatically rewrites website links for convenience.
*
* Consider the case when proxying to mydocs.com from `from.pattern="a.com/docs/*"`. Links on mydocs.com will not include the necessary `/docs` prefix and will break. For example, a homepage link `a.href="/"` will incorrectly link to your homepage instead of the documentation homepage.
*
* @defaultValue true
*/
rewriteLinks?: boolean
/**
* Improve your website performance by providing resource hints to the browser before the final response is ready. Early hints is a powerful tool that will speed up your website when used correctly. [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103) about using Early Hints correctly to improve website performance.
*
* Proxyflare provides several modes that allow for fine-tuned policies to avoid over-hinting on resource-heavy websites. We recommend trying different policies to see which works best for your site by using this [handy inspector tool](https://www.debugbear.com/resource-hint-validator).
*
* @defaultValue false
*
* @param true - send early hints for all script tags, stylesheets, and images on your site.
*
* @param mode - `provide-stylesheets`: send early hints for all script tags, stylesheets, and images on your site.
*
* @param mode - `provide-images`: send early hints on all script tags, but images must be explicitly tagged for early hinting. Add a `data-early-hints="preload"` attribute to each image you want to early hint on.
*
* <img src="cat.jpg" data-early-hints="preload" />
*
*/
earlyHints?:
| boolean
| {
mode: ("provide-images" | "provide-stylesheets" | "provide-scripts")[]
}
/**
* Most websites make additional requests for stylesheets, images, and other static content required to render, format, and populate the page. Enumerate resource requests to tell Proxyflare to match them to your route.
*
* @remarks
*
* Resources a couple important caveats. Proxyflare does its best to route traffic, but if two website have identical static resource folders, all it can do is guess.
*
* Take the case where two websites both have `to.website.resources:["a.com/images/*"]`. On an request for `a.com/images/cat.jpg`, Proxyflare sends a request to both websites for the resource, and whichever one responds first wins. This can be problematic in the case where both sites contain identical resources. For example, `logo.jpg` for one website might render on the other site!
*
* The recommended solution is to disambiguate the resources for each website. For example, change the images directory of the first website to `images-a` and the second to `images-b`. Then, Proxyflare will know exactly where to send traffic for each website.
*
* @example
* Request: `a.com/images/its-morbin-time.jpg`
* from.pattern: `a.com/my-site/*`
* to.url: `b.com`
* to.website.resources: `["a.com/images/*"]`
* ✅ Proxies traffic on `a.com/images/*` to `b.com`
*
* @example
* Request: `a.com/static/lib/jquery.js`
* from.pattern: `a.com/my-site/*`
* to.url: `b.com`
* to.website.resources: `["a.com/images/*", "a.com/static/lib/jquery.js"]`
* ✅ Proxies the jquery script to `b.com`
*/
resources?: string[]
cors?: CORSOptions
}
/**
* Proxied request timeout in milliseconds
* @defaultValue 30000 (30 seconds)
*/
timeoutMs?: number
}
type ToR2Bucket = ToBase & {
/**
* Mount a private R2 bucket using the S3 API on any part of your domain by providing the bucket metadata and a valid [R2 API token](https://dash.cloudflare.com/?account=r2/overview/api-tokens).
* @example
* Mount `my-cats-bucket` on `a.com/cats`
* Request: `a.com/cats/my-cat-1.png`
* from.pattern: `a.com/cats/*`
* to.r2Bucket: R2BucketOptions
*/
r2Bucket?: R2BucketOptions
url?: never
text?: never
}
type ToText = ToBase & {
url?: never
/**
* Text to render in the `ProxiedResponse` body. Set the Content-Type response header to differentiate between text, JSON, etc.
*/
text: string
}
type ToURL = ToBase & {
/**
* The url of the service to proxy traffic to. The url may be `http://` or `https://` and may include a `port`.
*
* For example, `to.url: http://a.com:3000` will send traffic to port `3000` on `a.com`.
*/
url: string
text?: never
}
EarlyHints
/**
* Improve your website performance by providing resource hints to the browser before the final response is ready. Early hints is a powerful tool that will speed up your website when used correctly. [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103) about using Early Hints correctly to improve website performance.
*
* Proxyflare provides several modes that allow for fine-tuned policies to avoid over-hinting on resource-heavy websites. We recommend trying different policies to see which works best for your site by using this [handy inspector tool](https://www.debugbear.com/resource-hint-validator).
*
* @defaultValue false
*
* @param true - send early hints for all script tags, stylesheets, and images on your site.
* @param mode - `provide-images`: send early hints on all images, but images must be explicitly tagged for early hinting. Add a `data-early-hints="preload"` attribute to each image you want to early hint on.
*
* <img src="cat.jpg" data-early-hints="preload" />
*
* @param mode - `provide-stylesheets`: send early hints for all stylesheets on your site.
* @param mode - `provide-scripts`: send early hints for all scripts on your site.
*
*/
type EarlyHints =
| boolean
| {
mode: ("provide-images" | "provide-stylesheets" | "provide-scripts")[]
}
R2BucketOptions
export interface R2BucketOptions {
accountId: string
bucketName: string
accessKeyId: string
secretAccessKey: string
}
CORSOptions
export interface CORSOptions {
/**
* Configures the `Access-Control-Allow-Origin` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
*
* Possible values:
* - boolean - set to `true` to reflect the request origin, or set to `false` to disable CORS.
* - string[] - an array of acceptable origins.
* - `*` - allow any origin to access the resource
*/
origin?: boolean | string[] | "*"
/**
* Configures the `Access-Control-Allow-Methods` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods)
*
* Expects an array of valid HTTP methods or `*`. If not specified, defaults to reflecting the method specified in the request’s `Access-Control-Request-Method` header.
*/
methods?: Methods[] | "*"
/**
* Configures the `Access-Control-Expose-Headers` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)
*
* Expects an array of HTTP headers or `*`. If not specified, no custom headers are exposed.
*/
exposedHeaders?: string[] | "*"
/**
* Configures the `Access-Control-Allow-Headers` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
*
* Expects an array of HTTP headers or `*`. If not specified, defaults to reflecting the headers specified in the request’s `Access-Control-Request-Headers` header.
*/
allowedHeaders?: string[] | "*"
/**
* Configures the `Access-Control-Allow-Credentials` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials)
*
* Set to `true` to pass the header, otherwise it is omitted.
*/
credentials?: boolean
/**
* Configures the `Access-Control-Max-Age` [CORS header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age)
*
* Set to an integer to pass the header, otherwise it is omitted.
*/
maxAge?: number
}