Route configuration

Overview

There are multiple types of routes in Cloudpack:

• A render route is a server-rendered route which can return HTML or other content, and optionally list JS entry files to be included with the route's HTML.
• A static route is served as-is.
• A redirect route redirects to a different URL.
• A bootstrap route is used for advanced side-loading scenarios.
• A proxy route forwards requests to another server or service.

The array of routes is specified under the routes property of cloudpack.config.json.

{
  "$schema": "https://unpkg.com/@ms-cloudpack/cli/schema/AppConfig.json",
  "routes": []
}

Common route options

All route types require a match.

match

Type: RouteMatch | RouteMatch[]

type RouteMatch = string | { path: string; domain?: string }

When specified as a string, represents the URL path to match. The match should usually start with a slash, e.g. '/my-route'. An array matches multiple paths.

Paths can also use wildcards (*), e.g. '/my-route/*' to match all paths under '/my-route/'. See the Express routing docs for the full supported syntax.

To create a catch-all fallback route, use "match": "*". This must be the last route.

When an object containing a domain property is provided, routes can match on a particular subdomain. Domains can also use wildcards (*) to match partial hostname matching, e.g. 'word.*' would match word.cloud.microsoft but not excel.cloud.microsoft.

Render route

This is a server-rendered route which can return HTML or other content.

Note that if any render (or bootstrap) route specifies an entry, this will overwrite any original exports map for the package. (Please talk to the team if this creates a problem for your scenario.)

Property	Type	Description
match (required)	`RouteMatch	RouteMatch[]`
serverEntry	string	Path to a TS, JS, or HTML file (relative to the app path) to render the route. Also supports exports map keys. A TS/JS file will be bundled before rendering, and must default export a custom render function.
renderScript (deprecated)	string	Like serverEntry but only supports JS or HTML, and won't be bundled if JS. Please talk to the team if you have a scenario where bundling the script causes a problem.
entry	string | string[]	Additional source file path(s) to bundle and include in the HTML, e.g. ./src/index.tsx. This overwrites any original exports map for the package.

Rendering HTML

HTML returned from a render route is assumed to be a page in the app, which loads Cloudpack-bundled JS and displays the status overlay. (If you need a completely "vanilla" HTML page for some reason, use a static route instead.)

With any of the HTML rendering options below, Cloudpack will bundle any provided entry files and automatically inject the bundled modules as script tags. It will also inject the import map and Cloudpack setup scripts, including the status overlay.

There are multiple options for rendering HTML routes, depending on the level of customization needed:

• No serverEntry/renderScript: Cloudpack will use a basic HTML page and inject scripts as described above.
• HTML serverEntry/renderScript: Cloudpack will load this file and inject scripts.
• TS or JS serverEntry (formerly JS renderScript): The custom render function in this file should return a string of HTML. Cloudpack will call the function and inject scripts in the returned HTML.

Rendering other content

Other content types can only be returned if you specify a JS/TS file as the serverEntry. See custom rendering for details.

Examples

These examples only cover basic cases. See custom rendering for cases involving a JS/TS serverEntry.

Suppose ./src/App.tsx initializes the app using React. To inject that script and the Cloudpack setup scripts on a basic HTML page, which is served at the root path:

{ "match": "/", "entry": "./src/App.tsx" }

As above, but with a custom HTML page ./static/index.html:

{
  "match": "/",
  "entry": "./src/App.tsx",
  "serverEntry": "./static/index.html"
}

To inject multiple entry files:

{ "match": "/", "entry": ["./src/App.tsx", "./src/extraSetup.ts"] }

Static route

Serves static asset(s) directly from a specified path, without modification by the Cloudpack server.

To customize the HTML for a page in the app, you should typically use a render route instead so that Cloudpack bootstrap scripts are injected (a static route does not inject scripts).

Property	Type	Description
match (required)	`RouteMatch	RouteMatch[]`
staticPath (required)	string	Path to the static asset(s), relative to the app root.

Examples

Route requests for /example.png to ./public/example.png:

{ "match": "/example.png", "staticPath": "./public/example.png" }

Serve a completely static HTML file (no Cloudpack scripts or entry scripts will be injected):

{ "match": "/boring", "staticPath": "./public/boring.html" }

Route any request under /images to a file under the ./images folder (do not use * in match here):

{ "match": "/images", "staticPath": "./images" }

Emulate a publicPath setting by attempting to route any unmatched requests to a file under ./public (this must be the last route):

{ "match": "*", "staticPath": "./public" }

Redirect route

Redirect from one path to another.

Property	Type	Description
match (required)	`RouteMatch	RouteMatch[]`
redirectTo (required)	string	Redirect to this path. See Express redirect docs for full supported syntax.

Examples

Redirect /foo to /bar:

{ "match": "/foo", "redirectTo": "/bar" }

Redirect root requests to /some-path:

{ "match": "/", "redirectTo": "/some-path" }

Bootstrap route

A bootstrap route is used in advanced cases where the app's HTML must be rendered by some official server, not the Cloudpack server. It returns the Cloudpack initialization JS (including references to the usual auto-injected scripts) which can be loaded and run on the page rendered by the other server.

Note that if any bootstrap or render route specifies an entry, this will overwrite any original exports map for the package. (Please talk to the team if this creates a problem for your scenario.)

Property	Type	Description
type (required)	'bootstrap'	Route type discriminator
match (required)	`RouteMatch	RouteMatch[]`
entry	string | string[]	Additional source file path(s) to bundle and include in the HTML, e.g. ./src/index.tsx. This overwrites any original exports map for the package.
deferScripts (optional)	boolean	If true, defers execution of scripts in the HTML until entry modules have loaded. Defaults to false.

Proxy route

A proxy route is used to forward incoming requests to another server or service. This is particularly useful for delegating specific API routes to backend services.

Property	Type	Description
match (required)	RouteMatch | RouteMatch[]	See match.
proxyTo (required)	string	The target URL to proxy requests to, including the protocol and host (e.g., https://api.example.com).
changeOrigin (optional)	boolean	For virtual hosted sites. When true, the origin of the host header will be changed to the target.
pathRewrite (optional)	Record<string, string>	Rewrite the target URL's path. The keys are treated as regular expressions to match incoming request paths, and the values replace the matched paths. For example, { "^/api": "" } removes the /api prefix.

For more information visit the http-proxy-middleware documentation.

Examples

Proxy requests from /auth to https://auth.example.com and change the origin header:

{
  "match": "/auth",
  "proxyTo": "https://auth.example.com",
  "changeOrigin": true
}

Proxy requests from /static to https://static.example.com and remove the /static prefix:

{
  "match": "/static",
  "proxyTo": "https://static.example.com",
  "pathRewrite": { "^/static": "" }
}