@ngrok/app-server 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +652 -77
- package/dist/build-id-C6sYO9Yp.js +126 -0
- package/dist/build-id-C6sYO9Yp.js.map +1 -0
- package/dist/{build-manifest-8NfD1wnO.js → build-manifest-UDNk81Ce.js} +24 -6
- package/dist/build-manifest-UDNk81Ce.js.map +1 -0
- package/dist/cli.js +45 -25
- package/dist/cli.js.map +1 -1
- package/dist/client-browser.d.ts +12 -0
- package/dist/client-browser.js +3 -0
- package/dist/client.d.ts +21 -0
- package/dist/client.js +27 -0
- package/dist/client.js.map +1 -0
- package/dist/compression-7_gToa8R.js +97 -0
- package/dist/compression-7_gToa8R.js.map +1 -0
- package/dist/create-server-DkTeIJ8L.js +1409 -0
- package/dist/create-server-DkTeIJ8L.js.map +1 -0
- package/dist/{deno-DNRgzHrk.js → deno-aqhikNMG.js} +2 -2
- package/dist/deno-aqhikNMG.js.map +1 -0
- package/dist/entry-CM6Ma-Tv.d.ts +626 -0
- package/dist/entry-CenmvESk.js +116 -0
- package/dist/entry-CenmvESk.js.map +1 -0
- package/dist/gzip-Doi4wqjX.js +294 -0
- package/dist/gzip-Doi4wqjX.js.map +1 -0
- package/dist/header-hook-Vzw9J9BY.js +159 -0
- package/dist/header-hook-Vzw9J9BY.js.map +1 -0
- package/dist/{index-oSE-tYRW.d.ts → index-Bo5G9LuQ.d.ts} +53 -14
- package/dist/index.d.ts +99 -269
- package/dist/index.js +47 -59
- package/dist/index.js.map +1 -1
- package/dist/listen-options-7TaXjyrk.js.map +1 -1
- package/dist/{load-entry-C03qqmhr.js → load-entry-CmkdlmDX.js} +8 -4
- package/dist/{load-entry-C03qqmhr.js.map → load-entry-CmkdlmDX.js.map} +1 -1
- package/dist/log-BP6xXXZl.js +122 -0
- package/dist/log-BP6xXXZl.js.map +1 -0
- package/dist/node-BFH82eeL.js +333 -0
- package/dist/node-BFH82eeL.js.map +1 -0
- package/dist/node-tBVQPjQv.js +41 -0
- package/dist/node-tBVQPjQv.js.map +1 -0
- package/dist/node-vite.d.ts +5 -4
- package/dist/node-vite.js +2 -17
- package/dist/node.d.ts +23 -4
- package/dist/node.js +2 -2
- package/dist/react-router-vite.d.ts +4 -3
- package/dist/react-router-vite.js +2 -20
- package/dist/react-router.d.ts +1 -1
- package/dist/react-router.js +8 -7
- package/dist/react-router.js.map +1 -1
- package/dist/request-context-BtQ87VYb.js +40 -0
- package/dist/request-context-BtQ87VYb.js.map +1 -0
- package/dist/response-edge-Bc1-C_Cx.js +327 -0
- package/dist/response-edge-Bc1-C_Cx.js.map +1 -0
- package/dist/response-writer-B7FoJjEE.js +289 -0
- package/dist/response-writer-B7FoJjEE.js.map +1 -0
- package/dist/script-hashes-hqUk6kG7.js +53 -0
- package/dist/script-hashes-hqUk6kG7.js.map +1 -0
- package/dist/{serve-Cleo8RMO.js → serve-Cc-ADdhZ.js} +3 -3
- package/dist/{serve-Cleo8RMO.js.map → serve-Cc-ADdhZ.js.map} +1 -1
- package/dist/stale-build-navigation-PnMLtTF8.js +339 -0
- package/dist/stale-build-navigation-PnMLtTF8.js.map +1 -0
- package/dist/stale-build-navigation-ypV7Ow4o.d.ts +141 -0
- package/dist/{start-CINALHxy.js → start-Cb3kknlF.js} +14 -19
- package/dist/start-Cb3kknlF.js.map +1 -0
- package/dist/static-files-Beju9riB.js +302 -0
- package/dist/static-files-Beju9riB.js.map +1 -0
- package/dist/tanstack-start-vite.d.ts +6 -5
- package/dist/tanstack-start-vite.js +2 -23
- package/dist/tanstack-start.d.ts +19 -2
- package/dist/tanstack-start.js +5 -14
- package/dist/tanstack-start.js.map +1 -1
- package/dist/{tcp-C-9AmFuM.js → tcp-Dd1Mt6sN.js} +6 -5
- package/dist/{tcp-C-9AmFuM.js.map → tcp-Dd1Mt6sN.js.map} +1 -1
- package/dist/trailing-slash-DX7NB88H.d.ts +36 -0
- package/dist/types-DLYxYS6M.d.ts +392 -0
- package/dist/vercel-vite.d.ts +35 -0
- package/dist/vercel-vite.js +142 -0
- package/dist/vercel-vite.js.map +1 -0
- package/dist/vercel.d.ts +35 -0
- package/dist/vercel.js +89 -0
- package/dist/vercel.js.map +1 -0
- package/dist/vite-B-GfswoH.js +22 -0
- package/dist/vite-B-GfswoH.js.map +1 -0
- package/dist/vite-D4hfj3ph.js +19 -0
- package/dist/vite-D4hfj3ph.js.map +1 -0
- package/dist/vite-DyrhyKEr.js +25 -0
- package/dist/vite-DyrhyKEr.js.map +1 -0
- package/dist/vite-iioAoxSt.js +752 -0
- package/dist/vite-iioAoxSt.js.map +1 -0
- package/dist/vite.d.ts +2 -2
- package/dist/vite.js +1 -1
- package/package.json +25 -4
- package/dist/build-manifest-8NfD1wnO.js.map +0 -1
- package/dist/deno-DNRgzHrk.js.map +0 -1
- package/dist/entry-BkdUub2S.js +0 -638
- package/dist/entry-BkdUub2S.js.map +0 -1
- package/dist/log-CsjaKM8U.js +0 -59
- package/dist/log-CsjaKM8U.js.map +0 -1
- package/dist/node-CG7qXuWZ.js +0 -58
- package/dist/node-CG7qXuWZ.js.map +0 -1
- package/dist/node-YWPGmzAk.js +0 -215
- package/dist/node-YWPGmzAk.js.map +0 -1
- package/dist/node-ZMowKZDB.js +0 -3
- package/dist/node-vite.js.map +0 -1
- package/dist/react-router-vite.js.map +0 -1
- package/dist/start-CINALHxy.js.map +0 -1
- package/dist/tanstack-start-vite.js.map +0 -1
- package/dist/types-BfCkS7kQ.d.ts +0 -203
- package/dist/vite-mYZ2Y69u.js +0 -144
- package/dist/vite-mYZ2Y69u.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,18 +1,80 @@
|
|
|
1
1
|
# @ngrok/app-server
|
|
2
2
|
|
|
3
|
-
A composable [Hono](https://hono.dev) app server for [React Router](https://reactrouter.com) and [TanStack Start](https://tanstack.com/start) apps. It replaces `@react-router/serve`, and it runs the same request pipeline in development and production, on Node, Bun, and Deno.
|
|
3
|
+
A composable [Hono](https://hono.dev) app server for [React Router](https://reactrouter.com) and [TanStack Start](https://tanstack.com/start) apps. It replaces `@react-router/serve`, and it runs the same request pipeline in development and production, on Node, Bun, and Deno, or as a Vercel Function.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Compared with `@react-router/serve`
|
|
6
6
|
|
|
7
|
-
-
|
|
7
|
+
`@react-router/serve` 8.5.1 is Express 5 with `compression()`, `express.static` for the client build, and a `morgan` text log that comes after the static files. `app-server` serves the same build faster. It also does more work for each request.
|
|
8
|
+
|
|
9
|
+
### Speed
|
|
10
|
+
|
|
11
|
+
On the React Router fixture app of this repo, `app-server` answers more requests each second than `@react-router/serve` on each route:
|
|
12
|
+
|
|
13
|
+
| Route | `app-server` | `@react-router/serve` | Change |
|
|
14
|
+
| --------------------------------------------------- | -----------: | --------------------: | -----: |
|
|
15
|
+
| `/`, a prerendered page | 27,353 | 17,611 | +55% |
|
|
16
|
+
| `/ssr`, a rendered page | 5,648 | 2,401 | 2.4× |
|
|
17
|
+
| `/assets/*.js`, 233 kilobytes (KB), 68 KB as brotli | 22,491 | 2,006 | 11× |
|
|
18
|
+
| `/hello.txt`, a prerendered file of 5 bytes | 29,131 | 22,278 | +31% |
|
|
19
|
+
|
|
20
|
+
The table gives requests per second for a client that sends `Accept-Encoding: gzip, deflate, br`, as a browser does. Most of the large gains come from compression. `compression()` compresses each response with brotli for each request, and `app-server` sends the copy that the build wrote.
|
|
21
|
+
|
|
22
|
+
With no `Accept-Encoding`, the gains are +17% for `/`, +15% for `/ssr`, +31% for `/assets/*.js`, and +23% for `/hello.txt`. In these numbers, `app-server` also adds the security headers, a request ID, a JSON log line, and the build ID to each response.
|
|
23
|
+
|
|
24
|
+
A CDN that keeps the `/assets/*` files makes the asset gain smaller for a visitor.
|
|
25
|
+
|
|
26
|
+
How we measured:
|
|
27
|
+
|
|
28
|
+
- Build the package with `pnpm run build`, then build `test/fixtures/react-router` with `react-router build`.
|
|
29
|
+
- In that directory, run `node build/server/app-server.js` and `pnpm exec react-router-serve build/server/index.js`, with `NODE_ENV=production`. Each server is one process. `pnpm install` installs `@react-router/serve` as a development dependency of this repo.
|
|
30
|
+
- Send load to each route with `oha -z 5s -c 64`: 64 connections for 5 seconds. Use `--disable-compression` for the runs with no `Accept-Encoding`.
|
|
31
|
+
- The table gives the median of 5 rounds. The two servers alternate in each round, and `app-server` got more requests each second in each round.
|
|
32
|
+
- The versions are Node.js 26.13, `@react-router/serve` 8.5.1, Express 5.3.0, `compression` 1.8.2, and `oha` 1.16.0. The machine is one Apple M3 Max with macOS.
|
|
33
|
+
|
|
34
|
+
### What it fixes
|
|
35
|
+
|
|
36
|
+
- Each page has one URL. A page URL with the other trailing-slash form gets a 308 to it, for rendered and prerendered pages. A prerendered page answers at its own URL with a 200.
|
|
8
37
|
- A prerendered resource route (`llms.txt`, `sitemap.xml`, a JSON API file) and each `.data` file keep the headers their loader sent: `Content-Type`, `Cache-Control`, CORS.
|
|
38
|
+
- A static file gets the brotli or gzip copy that the build wrote. `compression()` compresses each response again for each request.
|
|
9
39
|
- A streamed page under gzip reaches the client chunk by chunk.
|
|
10
40
|
- Each request gets one JSON log line in your format, static files included, and an `X-Request-Id`.
|
|
11
|
-
- Shutdown drains open requests with a deadline, and the keep-alive timeout outlasts the proxy's idle pool.
|
|
41
|
+
- Shutdown drains open requests with a deadline, and the keep-alive timeout outlasts the proxy's idle pool. `@react-router/serve` closes the server on `SIGTERM`, with no deadline and no readiness probe.
|
|
42
|
+
|
|
43
|
+
### What it adds
|
|
44
|
+
|
|
45
|
+
For a marketing site:
|
|
46
|
+
|
|
47
|
+
- [Redirects](#redirects) from a table, and [`noindex`](#preview-deploys) for preview deploys.
|
|
48
|
+
- [Markdown twins](#content-negotiation) for agents, with `Vary: Accept` and a `Link` header.
|
|
49
|
+
- [Security headers](#security-headers), and [a CSP for each document](#a-csp-for-each-document): script hashes for a prerendered page and a nonce for a rendered page.
|
|
50
|
+
- ETags, 304s, and byte ranges for each static file, so Safari plays a `<video>` from the client build.
|
|
51
|
+
- [One build for each environment](#environment): the `PUBLIC_` values go into each HTML document at serve time.
|
|
52
|
+
|
|
53
|
+
For a web app:
|
|
54
|
+
|
|
55
|
+
- [Deploys and open tabs](#deploys-and-open-tabs): after a deploy, the next navigation of an old tab loads its target as a document, so the old code never renders new data. The client module adds no request to a client navigation.
|
|
56
|
+
- [Health checks](#health-checks) at `/livez` and `/readyz`, and a delay before the drain.
|
|
57
|
+
- A [request body limit](#the-pipeline), and [`Cache-Control: private`](#the-pipeline) on each rendered page and data response with no `Cache-Control`, so a shared cache never keeps them for one user.
|
|
58
|
+
- [Logs](#logs) with W3C and Datadog trace IDs, a logger in each loader, and the client address behind a proxy.
|
|
59
|
+
- [Server-sent events](#long-lived-responses) that close at shutdown.
|
|
60
|
+
- An auth check that also protects each prerendered file. See [Protect pages](#protect-pages).
|
|
61
|
+
|
|
62
|
+
For each app:
|
|
63
|
+
|
|
64
|
+
- One pipeline for development and production, with the same headers and the same CSP.
|
|
65
|
+
- A [server build that runs with no install](#deploy), on Node.js, Bun, or Deno, or as a [Vercel Function](#deploy-to-vercel).
|
|
66
|
+
|
|
67
|
+
### What changes for your app
|
|
68
|
+
|
|
69
|
+
- The app needs Node.js 26+, Vite 8.3+, and React Router 8.5+. See [Requirements](#requirements).
|
|
70
|
+
- The package has ES modules only.
|
|
71
|
+
- A plugin is Hono middleware, not Express middleware.
|
|
72
|
+
- With `defaultPlugins()`, a request body over 10 mebibytes (MiB) gets a 413, and a page URL with a trailing slash gets a 308. Change both with the options of `defaultPlugins()`.
|
|
73
|
+
- The package does not support React Router `serverBundles`, and the app must serve at `/`. See [Limits](#limits).
|
|
12
74
|
|
|
13
75
|
## Requirements
|
|
14
76
|
|
|
15
|
-
- Node.js
|
|
77
|
+
- Node.js 26+, Bun 1.3+, or Deno 2.9+
|
|
16
78
|
- Vite 8.3+
|
|
17
79
|
- React Router 8.5+, or TanStack Start 1.169+
|
|
18
80
|
- An ES module app and server build. The package has no CommonJS build, and the Vite plugin refuses a CommonJS server build.
|
|
@@ -29,25 +91,20 @@ The server has three layers:
|
|
|
29
91
|
|
|
30
92
|
- The core: the request pipeline, the plugins, and `createServer`. It imports Hono and nothing else.
|
|
31
93
|
- A framework adapter: how the framework renders a request. `react-router` and `tanstack-start` come with the package.
|
|
32
|
-
- A host adapter: where the server runs. `node`
|
|
94
|
+
- A host adapter: where the server runs. `node` and `vercel` come with the package. `node` runs one long-lived process on Node, Bun, or Deno, such as in a Docker image. `vercel` runs the pipeline in one Vercel Function. See [Deploy to Vercel](#deploy-to-vercel).
|
|
33
95
|
|
|
34
|
-
Each adapter has a build side, which the Vite
|
|
96
|
+
Each adapter has a build side, which the Vite plugin uses, and a run side, which the server build imports.
|
|
35
97
|
|
|
36
98
|
Add the Vite plugin next to the framework's plugin. For React Router:
|
|
37
99
|
|
|
38
100
|
```ts
|
|
39
101
|
// vite.config.ts
|
|
40
102
|
import { appServer } from "@ngrok/app-server/vite";
|
|
41
|
-
import { node } from "@ngrok/app-server/node/vite";
|
|
42
|
-
import { reactRouterAdapter } from "@ngrok/app-server/react-router/vite";
|
|
43
103
|
import { reactRouter } from "@react-router/dev/vite";
|
|
44
104
|
import { defineConfig } from "vite";
|
|
45
105
|
|
|
46
106
|
export default defineConfig({
|
|
47
|
-
plugins: [
|
|
48
|
-
reactRouter(),
|
|
49
|
-
appServer({ framework: reactRouterAdapter(), host: node(), app: "./server.ts" }),
|
|
50
|
-
],
|
|
107
|
+
plugins: [reactRouter(), appServer()],
|
|
51
108
|
});
|
|
52
109
|
```
|
|
53
110
|
|
|
@@ -56,32 +113,38 @@ For TanStack Start:
|
|
|
56
113
|
```ts
|
|
57
114
|
// vite.config.ts
|
|
58
115
|
import { appServer } from "@ngrok/app-server/vite";
|
|
59
|
-
import { node } from "@ngrok/app-server/node/vite";
|
|
60
|
-
import { tanstackStartAdapter } from "@ngrok/app-server/tanstack-start/vite";
|
|
61
116
|
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
|
|
62
117
|
import viteReact from "@vitejs/plugin-react";
|
|
63
118
|
import { defineConfig } from "vite";
|
|
64
119
|
|
|
65
120
|
export default defineConfig({
|
|
66
|
-
plugins: [
|
|
67
|
-
tanstackStart(),
|
|
68
|
-
viteReact(),
|
|
69
|
-
appServer({ framework: tanstackStartAdapter(), host: node(), app: "./server.ts" }),
|
|
70
|
-
],
|
|
121
|
+
plugins: [tanstackStart(), viteReact(), appServer()],
|
|
71
122
|
});
|
|
72
123
|
```
|
|
73
124
|
|
|
125
|
+
`appServer` has three options. Each one has a default:
|
|
126
|
+
|
|
127
|
+
- `framework`: the framework adapter. Default: the adapter of the framework plugin in the Vite config. The plugin of React Router is `reactRouter()`, and the plugin of TanStack Start is `tanstackStart()`. If the config has neither plugin or both, Vite stops with an error. Then pass `reactRouterAdapter()` from `@ngrok/app-server/react-router/vite` or `tanstackStartAdapter()` from `@ngrok/app-server/tanstack-start/vite`.
|
|
128
|
+
- `host`: the host adapter. Default: `node()` from `@ngrok/app-server/node/vite`.
|
|
129
|
+
- `app`: the module whose default export is the app, relative to the Vite root. Default: `server.ts`, else `server.js`, in the Vite root. If neither file exists, the server uses the default plugins.
|
|
130
|
+
|
|
131
|
+
An option that you set replaces its default. Set it for a third-party adapter or for an app in another file:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
appServer({ framework: reactRouterAdapter(), host: node(), app: "./src/app.ts" });
|
|
135
|
+
```
|
|
136
|
+
|
|
74
137
|
Write the server. Its default export is the app:
|
|
75
138
|
|
|
76
139
|
```ts
|
|
77
140
|
// server.ts
|
|
78
141
|
import { createServer, defaultPlugins } from "@ngrok/app-server";
|
|
79
142
|
|
|
80
|
-
|
|
81
|
-
app.get("/livez", (c) => c.text("ok"));
|
|
82
|
-
export default app;
|
|
143
|
+
export default createServer({ plugins: defaultPlugins() });
|
|
83
144
|
```
|
|
84
145
|
|
|
146
|
+
`defaultPlugins()` answers the health probes at `/livez` and `/readyz`, and sends the build ID that tells an open tab about a deploy. Its options turn on the other plugins, each in its correct place. See [The pipeline](#the-pipeline).
|
|
147
|
+
|
|
85
148
|
Run it:
|
|
86
149
|
|
|
87
150
|
```json
|
|
@@ -93,104 +156,566 @@ Run it:
|
|
|
93
156
|
}
|
|
94
157
|
```
|
|
95
158
|
|
|
96
|
-
`appServer` adds `server/app-server.js` to the server build, next to the framework's own entry, which does not change. The file bundles `server.ts` with the framework's server module, so the server gets the app's path aliases and its one copy of the framework.
|
|
159
|
+
`appServer` adds `server/app-server.js` to the server build, next to the framework's own entry, which does not change. The file bundles `server.ts` with the framework's server module, so the server gets the app's path aliases and its one copy of the framework. The build also bundles the dependencies, so the build directory runs with no install. See [Deploy](#deploy).
|
|
160
|
+
|
|
161
|
+
After the build and after the prerender pass, `appServer` writes a gzip copy (`.<file>.gz`) and a brotli copy (`.<file>.br`) next to each text file of 1 kibibyte (KiB) or more in the client build, HTML pages included. It writes the gzip copy when it is smaller than the file, and the brotli copy when it is smaller than the gzip copy. `app-server serve` sends the copy that the client's `Accept-Encoding` prefers, brotli before gzip, so it does not compress the file for each request. Each copy is a dotfile, so it has no URL of its own: a `skip` rule or an auth check for the file also blocks its copies. The build does not change a `.gz` or `.br` file of the app. The copies include the prerendered files, in any plugin order. The brotli copies use quality 9, not 11: on a docs build with 70 megabytes (MB) of text, quality 11 adds 46 s to the build, and quality 9 adds 0.6 s for copies that are 9% larger. `appServer` gives a list of Vite plugins, so put it in `plugins` as it is.
|
|
97
162
|
|
|
98
163
|
The build exports `appServer`, and the CLI calls it. So the copy of this package in the build runs the server, and the CLI's copy runs nothing. The CLI refuses a build from a version of this package with another entry protocol.
|
|
99
164
|
|
|
100
|
-
A React Router app with no Vite plugin also works: `app-server serve build/server/index.js` reads a plain React Router build and runs it with the CLI's copy, the node host, and the default plugins. In that build, a route that calls `shutdownSignal()`, `eventStream()`, or `
|
|
165
|
+
A React Router app with no Vite plugin also works: `app-server serve build/server/index.js` reads a plain React Router build and runs it with the CLI's copy, the node host, and the default plugins. In that build, a route that calls `shutdownSignal()`, `eventStream()`, `requestContext()`, or `cspNonce()` must import the CLI's copy, so do not bundle `@ngrok/app-server` into it.
|
|
101
166
|
|
|
102
167
|
## Commands
|
|
103
168
|
|
|
104
169
|
- `app-server start`: development. Vite in middleware mode inside the pipeline, with HMR on the same port. It needs the `appServer` plugin. Each request loads the latest server entry, so an edit to a route or to `server.ts` applies at once. The port is `--port`, else `PORT`, else Vite's `server.port`. When that port is in use, `start` tries each next port, unless Vite's `server.strictPort` is true. The host is `HOST`, else Vite's `server.host`. On `SIGTERM` or `SIGINT`, it stops Vite and the server, then exits.
|
|
105
|
-
- `app-server
|
|
170
|
+
- `node build/server/app-server.js`: production, with no install. Use `dist/server/app-server.js` for TanStack Start. It reads `PORT` and `HOST`, and it drains on `SIGTERM` or `SIGINT`, as `app-server serve` does. It has no `--port`. It sets `NODE_ENV` to `production` when `NODE_ENV` has no value.
|
|
171
|
+
- `app-server serve [path]`: production. With no path, it runs the first of `build/server/app-server.js` (React Router), `dist/server/app-server.js` (TanStack Start), and `build/server/index.js` (a plain React Router build). The port is `--port`, else `PORT`, else 3000. The host is `HOST`, else every interface. A port in use stops startup at once. On `SIGTERM` or `SIGINT`, it drains, then exits, even when the app left a timer. A server process serves the client build that was there at start. A deploy starts a new process.
|
|
172
|
+
|
|
173
|
+
`-p` is short for `--port`. `--help` writes the usage. A bad argument writes a message and the usage, and exits with code 1.
|
|
106
174
|
|
|
107
|
-
On Bun, run `bun node_modules/@ngrok/app-server/dist/cli.js serve`. On Deno, run `deno run --allow-net --allow-env --allow-read --allow-sys node_modules/@ngrok/app-server/dist/cli.js serve`. For `start` on Deno, also give `--allow-ffi --allow-write --ignore-read=/proc/sys/fs/binfmt_misc/WSLInterop`. Vite loads its native bundler and writes its cache. On Linux, Vite also reads a WSL file that Deno gives only to `--allow-all`.
|
|
175
|
+
On Bun, run `bun build/server/app-server.js`, or `bun node_modules/@ngrok/app-server/dist/cli.js serve`. On Deno, run `deno run --allow-net --allow-env --allow-read --allow-sys build/server/app-server.js`, or give the same flags to `node_modules/@ngrok/app-server/dist/cli.js serve`. A native package on Deno also needs `--allow-ffi`. For `start` on Deno, also give `--allow-ffi --allow-write --ignore-read=/proc/sys/fs/binfmt_misc/WSLInterop`. Vite loads its native bundler and writes its cache. On Linux, Vite also reads a WSL file that Deno gives only to `--allow-all`.
|
|
176
|
+
|
|
177
|
+
## Deploy
|
|
178
|
+
|
|
179
|
+
`vite build`, or `react-router build`, writes a server build that runs with no `npm install`. Copy the build directory alone, and run its server entry:
|
|
180
|
+
|
|
181
|
+
- `appServer` bundles each dependency into the server build. For the build, it sets `ssr.noExternal: true`, unless the app sets its own `ssr.noExternal` or sets `ssr.external: true`.
|
|
182
|
+
- Some packages stay external: each package in the app's `ssr.external` or in the bundler's `external` option, the whole package of an external subpath, each peer dependency of a package that the app keeps external, the peers of each peer, each native package, and each package that reads a file next to its own module. So the bundle and an external package use one copy of a package, such as `react` for a component library. For a `RegExp` or a function in the bundler's `external` option, the build tests the name of each package in the `dependencies`, `optionalDependencies`, and `devDependencies` of the app. It keeps the peers of each match external too. A package is native when a `.node` file is in it, or in a package of its `dependencies` or `optionalDependencies`. For example, `oxc-parser` gets its addon from `@oxc-parser/binding-linux-x64-gnu`. A package reads a file next to its module when the file that an import resolves to has `new URL("./…", import.meta.url)`, `fileURLToPath(import.meta.url)`, or `import.meta.dirname`. For example, `@vercel/og` reads `resvg.wasm` so.
|
|
183
|
+
- The build copies each external package, whole, with its installed dependencies, into `node_modules` in the server build. Each file stays where its package expects it, so CommonJS, a file read through `__dirname`, and a `.node` addon work.
|
|
184
|
+
- The build copies each package in `ssr.external`, also when no code imports it. It also copies each package that the app's code gives to `require.resolve()` or `import.meta.resolve()` as a string, such as `require.resolve("@fontsource/inter/files/inter-latin-400-normal.woff")`. When the code makes the name at run time, add the package to `ssr.external`.
|
|
185
|
+
- The build writes a `package.json` with `"type": "module"` into the server build, so Node, Bun, and Deno load it as ES modules and find its `node_modules`.
|
|
186
|
+
|
|
187
|
+
The copy holds only the native addon that the install put on the build machine. So run the build on the platform of the server, such as in the builder stage of a Docker image:
|
|
188
|
+
|
|
189
|
+
```dockerfile
|
|
190
|
+
FROM node:26-slim AS build
|
|
191
|
+
WORKDIR /app
|
|
192
|
+
COPY package.json package-lock.json ./
|
|
193
|
+
RUN npm ci
|
|
194
|
+
COPY . .
|
|
195
|
+
RUN npm run build
|
|
196
|
+
|
|
197
|
+
FROM gcr.io/distroless/nodejs26-debian13
|
|
198
|
+
WORKDIR /app
|
|
199
|
+
COPY --from=build /app/build ./build
|
|
200
|
+
EXPOSE 3000
|
|
201
|
+
# The image runs `node` with these arguments.
|
|
202
|
+
CMD ["build/server/app-server.js"]
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
For TanStack Start, copy `dist`, and run `dist/server/app-server.js`.
|
|
206
|
+
|
|
207
|
+
## Deploy to Vercel
|
|
208
|
+
|
|
209
|
+
The `vercel` host runs the pipeline in one Node.js Vercel Function. Vercel's content delivery network (CDN) serves the hashed files.
|
|
210
|
+
|
|
211
|
+
Use `vercel()` as the host:
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
// vite.config.ts
|
|
215
|
+
import { vercel } from "@ngrok/app-server/vercel/vite";
|
|
216
|
+
|
|
217
|
+
appServer({ host: vercel() });
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
After the build, `vercel()` writes `.vercel/output` (the Build Output API, version 3) in the Vite root. Deploy it with `vercel deploy --prebuilt`. Do not add `vercelPreset()` from `@vercel/react-router`. To build one app for Docker and for Vercel, choose the host from an environment variable, such as `appServer(process.env.VERCEL === "1" ? { host: vercel() } : {})`.
|
|
221
|
+
|
|
222
|
+
The output has two parts:
|
|
223
|
+
|
|
224
|
+
- `static/`: the files under `/assets/` and the other `cdnPaths`. The CDN serves them. Each file under `/assets/` gets `Cache-Control: public, max-age=31536000, immutable`. A request under `/assets/` with no file goes to the function, which sends a 404 with `Cache-Control: no-store`. A request under another CDN path with no file goes through the pipeline, as on the node host.
|
|
225
|
+
- `functions/index.func/`: the function for each other request. It has the whole server build, which runs with no install (see [Deploy](#deploy)), and the rest of the client build. The Node.js version of the function is the version that ran the build.
|
|
226
|
+
|
|
227
|
+
Prerendered pages come from the function, so they get the same pipeline as rendered pages: the security headers, the CSP, the redirects, and the markdown twins. To let the CDN keep a page, send `s-maxage` or `CDN-Cache-Control` in its headers, such as with the `headers` option of [`prerendered`](#prerendered-headers). Then a page calls the function only on a CDN miss.
|
|
228
|
+
|
|
229
|
+
`vercel()` takes:
|
|
230
|
+
|
|
231
|
+
- `cdnPaths`: more URL path prefixes for the CDN, such as `["/blog-assets/"]`. Each starts and ends with `/`. Their files skip the pipeline, and the function does not carry them. Vercel limits a function to 250 MB, so put a large directory of the client build here. Default none.
|
|
232
|
+
- `cdnHeaders`: headers for each CDN file, such as CORS headers. Default none.
|
|
233
|
+
- `regions`, `memory`, and `maxDuration`: the function's Vercel config. Default the project's.
|
|
234
|
+
|
|
235
|
+
The function differs from a long-lived process:
|
|
236
|
+
|
|
237
|
+
- Vercel starts and stops it. Each plugin's `setup` runs on the first request of each instance. If a `setup` throws, that request fails, and the next request runs each `setup` again. `onShutdown` never runs, and `shutdownSignal()` never aborts.
|
|
238
|
+
- The request scheme comes from `X-Forwarded-Proto`, and the client address comes from `X-Real-IP`, because Vercel sets both headers. Do not set `trustForwardedProto` or `trustedProxyHops`. Behind another proxy, such as the ngrok edge, the client address is the proxy's.
|
|
239
|
+
- The function does not gzip a response, because the CDN compresses each response. It still sends the build's `.<file>.br` and `.<file>.gz` copies.
|
|
240
|
+
- The deploy gives each file of the function one fixed modification time. So the function uses the time of the build for each file, and the ETag of each file it sends changes with each build.
|
|
241
|
+
- `app-server serve` cannot run the build. Use `app-server start` for development, as with the node host.
|
|
108
242
|
|
|
109
243
|
## The pipeline
|
|
110
244
|
|
|
111
245
|
`createServer` runs the plugins in list order, then the app's own Hono routes, then the framework. `defaultPlugins()` returns this order:
|
|
112
246
|
|
|
113
|
-
1. `
|
|
114
|
-
2. `
|
|
115
|
-
3. `
|
|
116
|
-
4. The `
|
|
117
|
-
5. `
|
|
118
|
-
6. `
|
|
119
|
-
|
|
120
|
-
`
|
|
247
|
+
1. `health()`: the liveness and readiness probes at `/livez` and `/readyz`. A probe skips the access log. `defaultPlugins({ health })` changes them, and `false` turns them off. See [Health checks](#health-checks).
|
|
248
|
+
2. `requestId()`: reuses a valid incoming `X-Request-Id`, else makes a UUID, and echoes it.
|
|
249
|
+
3. `accessLog({ redactQuery })`: one line per request when the response ends, for the response that leaves the server, with Datadog standard attributes (`http.status_code`, `network.bytes_written`, `duration` in nanoseconds). Query values are `REDACTED` by default.
|
|
250
|
+
4. `streamingCompress()`: gzip that flushes after each chunk. Chunks that the body has queued together go out as one, up to 16 KiB, so a rendered page costs fewer flushes. When the body ends by the time the gzip stream finishes its last chunk, that chunk and the gzip trailer go out together. On the node host, a body that ends with its first chunk, up to 64 KiB, uses a zlib stream from a pool, so a small page costs no new zlib stream. The pool keeps up to 16 streams between responses, about 4.3 MiB in all. A stream takes only such a body, and only one at least as long as each earlier body of that stream, so the gzip bytes of a body depend on that body alone. It skips encoded, partial, and `no-transform` responses, and a body under 1,024 bytes: by its `Content-Length`, or a body from a string. It adds `Accept-Encoding` to `Vary` only on a type that it can gzip. A static file with a compressed copy from the build gets that copy, and this plugin skips it. It follows the `q` values of `Accept-Encoding`, and `q=0` refuses gzip. The host gives the gzip stream. On a host with none, the plugin does nothing.
|
|
251
|
+
5. `securityHeaders()`: safe default security headers on each response, prerendered pages included. `defaultPlugins({ securityHeaders })` changes them, and `false` turns them off. See [Security headers](#security-headers).
|
|
252
|
+
6. `bodyLimit({ maxBytes })`: a 413 for a request body over `defaultPlugins({ bodyLimit })`, 10 mebibytes (MiB) by default. `false` turns it off. A `Content-Length` that is too large gets the 413 before the app runs. A streamed body errors when it passes the limit. When the app reads the body before it answers, the response becomes a 413. When the app streams the body into its response, the response stream errors. A `bodyLimit` that is not a whole number of 0 or more stops startup. The body streams. The plugin does not read it into memory.
|
|
253
|
+
7. The plugins of the named options. They see every response, prerendered pages included:
|
|
254
|
+
- `noindex()`, with `defaultPlugins({ noindex: true })`. See [Preview deploys](#preview-deploys).
|
|
255
|
+
- `buildId()`, on by default. `defaultPlugins({ buildId })` changes it, and `false` turns it off. See [Deploys and open tabs](#deploys-and-open-tabs).
|
|
256
|
+
- `contentSecurityPolicy()`, with `defaultPlugins({ contentSecurityPolicy })`. See [A CSP for each document](#a-csp-for-each-document).
|
|
257
|
+
- The plugin from `runtimeEnv()`, with `defaultPlugins({ env })`. See [Environment](#environment).
|
|
258
|
+
8. The `beforeStatic` plugins: the app's own plugins that see every response, prerendered pages included, such as an auth check. They come after the plugins of the named options, so they get the CSP nonce, and their responses get the headers of those plugins.
|
|
259
|
+
9. `assets()`: `/assets/*` with a one-year immutable cache. A missing asset gets a plain 404 with `Cache-Control: no-store`. In development, Vite serves here. See [Deploys and open tabs](#deploys-and-open-tabs).
|
|
260
|
+
10. `redirects(rules)`, when `defaultPlugins({ redirects })` has rules: a redirect from each old URL to its new URL. See [Redirects](#redirects).
|
|
261
|
+
11. `trailingSlash({ mode })`: a 308 from a page URL to the same URL in the site's trailing-slash form. See [Trailing slashes](#trailing-slashes).
|
|
262
|
+
12. `prerendered({ headers, rewrite, skip, cacheControl })`: every file in the client build, with an ETag, a 304 for a matching `If-None-Match`, and a 206 for one byte range of a file that is not HTML. An HTML page, a markdown file, and a data file of the framework get `Cache-Control: public, max-age=0, must-revalidate`, and every other file gets `public, max-age=3600, stale-while-revalidate=86400`. A captured header, the `headers` option, and `cacheControl` change it. A file with a compressed copy from the build gets `Vary: Accept-Encoding`. A client gets the copy that its `Accept-Encoding` prefers, brotli before gzip, with no byte ranges and an ETag for that encoding. A `no-transform` response never gets a copy, and an HTML page gets none when `runtimeEnv` adds values to it. A directory answers with its `index.html`. Each file has one URL: `/a//b`, `/a/index.html`, and `/a%2Fb` go on to the framework. Dotfiles stay private, except `/.well-known/`. A path with no file, or a path that `skip` matches, goes on to the framework.
|
|
263
|
+
13. `privateDocuments()`: `Cache-Control: private, no-cache` on each HTML document and each framework data response (such as a React Router `.data` request) from the app's routes or the framework that has no `Cache-Control`. A shared cache then never keeps a page or loader data that the server rendered for one user. A response with its own `Cache-Control` keeps it. A resource route that sends per-user JSON sets its own `Cache-Control`.
|
|
264
|
+
|
|
265
|
+
A route that takes a body larger than the limit needs a higher `bodyLimit` for the whole app, because each request passes the limit before it reaches a route.
|
|
266
|
+
|
|
267
|
+
`defaultPlugins()` is a plain array, so you can filter it or splice into it. Two plugins of one named option, such as `defaultPlugins()` with a second `buildId()`, stop startup. One would replace the headers of the other, so the value that the app gave would be lost. Use the option. A plugin is Hono middleware plus optional hooks:
|
|
121
268
|
|
|
122
269
|
```ts
|
|
270
|
+
import { withHeaderHook } from "@ngrok/app-server";
|
|
123
271
|
import type { Plugin } from "@ngrok/app-server";
|
|
124
272
|
|
|
125
|
-
const
|
|
126
|
-
name: "
|
|
127
|
-
middleware: async (c, next) =>
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
273
|
+
const frameOptions: Plugin = {
|
|
274
|
+
name: "frame-options",
|
|
275
|
+
middleware: async (c, next) =>
|
|
276
|
+
withHeaderHook(c, next, (response) => {
|
|
277
|
+
response.set("X-Frame-Options", "DENY");
|
|
278
|
+
}),
|
|
131
279
|
setup: (info) => {}, // once, before the first request; a throw stops startup
|
|
132
280
|
onShutdown: async () => {}, // at shutdown, while the listeners drain, up to the deadline
|
|
133
281
|
};
|
|
134
282
|
```
|
|
135
283
|
|
|
284
|
+
A plugin that sets a header on the response uses `withHeaderHook`. The hook changes the head once, where the response leaves, after the later stages and after the code that each stage runs after `await next()`. The hook of an inner stage runs first, so an outer stage has the last word. On Node.js and Vercel, the hooks change the list of headers that the server writes, so the response needs no copy. So code after `await next()` sees the response of the later stages without the changes of their hooks. To read or change the final headers, use a hook. A hook can read `requestContext()`. A hook that throws gets the answer of the app's `onError`, as a stage that throws does. On Node.js and Vercel, a wrapper of the app's `fetch` gets the response before the hooks: a header that it sets or deletes goes out, but it does not see the headers that the hooks set. In development, Vite answers some requests itself, such as source modules and `public/` files, and sends the response before the earlier stages get it back. The hooks also run on those responses, before Vite sends the head, so each response gets the same headers in development and in production. The static stages and `streamingCompress()` also run the hooks on a view of the headers before they choose a body, so a `no-transform`, a `Content-Encoding`, or a `Content-Range` from a hook keeps the body as it is. So a hook runs two or three times for a response with gzip or a compressed copy. Each run must give the same headers, and a hook must do nothing else, such as log, count, or store a value. A view run can come before the code that a stage runs after `await next()`, and a throw in it changes nothing. A hook can `get`, `has`, `set`, `append`, and `delete` a header.
|
|
285
|
+
|
|
136
286
|
A plugin that changes a response with a value it reads at run time, as `runtimeEnv` and `buildId` do, returns that value from `etagPart`. The server adds it to the ETag of each static file that the request reaches after the plugin, so a 304 never keeps a response made with an old value.
|
|
137
287
|
|
|
138
288
|
```ts
|
|
139
289
|
const version: Plugin = {
|
|
140
290
|
name: "version",
|
|
141
291
|
etagPart: () => process.env.APP_VERSION,
|
|
142
|
-
middleware: async (c, next) =>
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
292
|
+
middleware: async (c, next) =>
|
|
293
|
+
withHeaderHook(c, next, (response) => {
|
|
294
|
+
response.set("X-App-Version", process.env.APP_VERSION ?? "dev");
|
|
295
|
+
}),
|
|
146
296
|
};
|
|
147
297
|
```
|
|
148
298
|
|
|
149
|
-
|
|
299
|
+
A `beforeStatic` plugin that changes the bytes of an HTML page, as `runtimeEnv` does, calls `c.set("rewritesHtml", true)` before its `next()`. The static stages then send the HTML file as it is on disk, not its compressed copy. Without it, a client that accepts gzip or brotli gets the copy, with a `Content-Encoding` that the plugin must not change.
|
|
150
300
|
|
|
151
|
-
|
|
301
|
+
## Protect pages
|
|
152
302
|
|
|
153
|
-
|
|
154
|
-
import { readdirSync } from "node:fs";
|
|
303
|
+
`prerendered()` answers before the app's own routes and before the framework. So an auth check in a loader or in a `server.ts` route never runs for a prerendered file. A prerendered app shell at `/app` goes to a visitor with no session.
|
|
155
304
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
305
|
+
Use one of these two fixes:
|
|
306
|
+
|
|
307
|
+
- Put the auth check in `beforeStatic`. It then runs before each prerendered file and its data file.
|
|
308
|
+
- Send the private paths to the framework with `prerendered({ skip })`, and keep the auth check in the app.
|
|
309
|
+
|
|
310
|
+
An auth plugin sets `Cache-Control: private` on each response that it lets through. Else a CDN can give a protected file to every visitor.
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
import { createServer, defaultPlugins, withHeaderHook } from "@ngrok/app-server";
|
|
314
|
+
import type { Plugin } from "@ngrok/app-server";
|
|
162
315
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
name: "vary-on-accept",
|
|
316
|
+
const auth: Plugin = {
|
|
317
|
+
name: "auth",
|
|
166
318
|
middleware: async (c, next) => {
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
c.header("Vary", "Accept", { append: true });
|
|
319
|
+
if (!c.req.path.startsWith("/app")) {
|
|
320
|
+
return next();
|
|
170
321
|
}
|
|
322
|
+
if (!(await hasSession(c.req.raw))) {
|
|
323
|
+
return c.redirect("/login", 302);
|
|
324
|
+
}
|
|
325
|
+
await withHeaderHook(c, next, (response) => {
|
|
326
|
+
response.set("Cache-Control", "private, no-cache");
|
|
327
|
+
});
|
|
171
328
|
},
|
|
172
329
|
};
|
|
173
330
|
|
|
331
|
+
export default createServer({ plugins: defaultPlugins({ beforeStatic: [auth] }) });
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
`hasSession` stands for the app's own session check.
|
|
335
|
+
|
|
336
|
+
## Security headers
|
|
337
|
+
|
|
338
|
+
`defaultPlugins()` runs `securityHeaders()`. It sets these headers on each response, prerendered pages included:
|
|
339
|
+
|
|
340
|
+
- `X-Content-Type-Options: nosniff`
|
|
341
|
+
- `Referrer-Policy: strict-origin-when-cross-origin`
|
|
342
|
+
- `Cross-Origin-Opener-Policy: same-origin`
|
|
343
|
+
- `Strict-Transport-Security: max-age=31536000`, on an HTTPS request only
|
|
344
|
+
|
|
345
|
+
A response that has one of these headers keeps its own value. `false` turns a header off, and `defaultPlugins({ securityHeaders: false })` turns them all off.
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
defaultPlugins({
|
|
349
|
+
securityHeaders: {
|
|
350
|
+
headers: {
|
|
351
|
+
"Cross-Origin-Opener-Policy": "same-origin-allow-popups",
|
|
352
|
+
"Strict-Transport-Security": "max-age=31536000; includeSubDomains",
|
|
353
|
+
"Content-Security-Policy": "frame-ancestors 'none'",
|
|
354
|
+
},
|
|
355
|
+
},
|
|
356
|
+
});
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
- `Cross-Origin-Opener-Policy: same-origin` breaks a pop-up that talks to the page through `window.opener`, such as some OAuth and payment pop-ups. Set `same-origin-allow-popups` for such a site.
|
|
360
|
+
- A browser keeps `Strict-Transport-Security` for its `max-age`. Add `includeSubDomains` only when each subdomain serves HTTPS. Behind a proxy that ends TLS, set `trustForwardedProto`, else the server sees an HTTP request and sends no HSTS.
|
|
361
|
+
- `Content-Security-Policy` has no default, so another site can put the page in a frame. Set `frame-ancestors 'none'` to stop that. The plugin adds the value as a second policy, next to the response's own policy, and a browser enforces both.
|
|
362
|
+
|
|
363
|
+
### A CSP for each document
|
|
364
|
+
|
|
365
|
+
`contentSecurityPolicy({ policy })` sets the `Content-Security-Policy` from `policy` on each HTML document that has none. `policy` gets the `script-src` source list that trusts the document's scripts, and the request's Hono context, so the policy can change by path:
|
|
366
|
+
|
|
367
|
+
- A rendered document gets `'nonce-…' 'strict-dynamic'`, with a new nonce for each request.
|
|
368
|
+
- A prerendered document gets `'self'` and the hash of each of its inline scripts, such as `'self' 'sha256-…'`. The `appServer` Vite plugin records the hashes. The prerender writes one nonce into the file, and every visitor can read it, so a nonce protects nothing. A hash does not carry to the imports of an inline module script, so this list has no `'strict-dynamic'`.
|
|
369
|
+
|
|
370
|
+
If the build recorded no hashes for an HTML file, the list is only `'self'`, and the browser blocks the file's inline scripts. A 304 for a prerendered document gets the policy too, because a browser replaces the policy of its cached copy with the policy of the 304. The `contentSecurityPolicy` option of `defaultPlugins()` puts the plugin before the static stages, so it sees the prerendered documents.
|
|
371
|
+
|
|
372
|
+
In development, `app-server start` sends the same policy. A rendered page gets a nonce. An HTML file in Vite's public directory, such as `public/offline.html`, gets the hashes of its inline scripts, so a script that production blocks is blocked in development too.
|
|
373
|
+
|
|
374
|
+
```ts
|
|
174
375
|
createServer({
|
|
175
376
|
plugins: defaultPlugins({
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
rewrite: (path, c) =>
|
|
179
|
-
markdownPaths.has(twin(path)) && c.req.header("Accept")?.includes("text/markdown")
|
|
180
|
-
? twin(path)
|
|
181
|
-
: path,
|
|
377
|
+
contentSecurityPolicy: {
|
|
378
|
+
policy: (scriptSrc) => `script-src ${scriptSrc}; object-src 'none'; base-uri 'none'`,
|
|
182
379
|
},
|
|
183
380
|
}),
|
|
184
381
|
});
|
|
185
382
|
```
|
|
186
383
|
|
|
187
|
-
|
|
384
|
+
Give the nonce to the framework's render with `cspNonce()` from `@ngrok/app-server/client`. On the server, it gives the nonce of the request. In the browser, it reads the nonce from the document, so the hydration matches. It gives `undefined` when the page has no nonce. A bundler that resolves the `browser` export condition, such as Vite for the client build, gets a `cspNonce()` with no server code.
|
|
385
|
+
|
|
386
|
+
In React Router, give it to the render in `app/entry.server.tsx`:
|
|
387
|
+
|
|
388
|
+
```tsx
|
|
389
|
+
import { cspNonce } from "@ngrok/app-server/client";
|
|
390
|
+
|
|
391
|
+
const nonce = cspNonce();
|
|
392
|
+
const { pipe } = renderToPipeableStream(
|
|
393
|
+
<ServerRouter context={routerContext} url={request.url} nonce={nonce} />,
|
|
394
|
+
{ nonce /* , … */ },
|
|
395
|
+
);
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
`<HydratedRouter>` takes no nonce, so in the browser `<Links>`, `<ScrollRestoration>`, and `<Scripts>` render no nonce, and React warns that the hydration does not match. Give them the nonce in the root `Layout`. Give it also to each inline script of the app, such as a theme script:
|
|
399
|
+
|
|
400
|
+
```tsx
|
|
401
|
+
// app/root.tsx
|
|
402
|
+
import { cspNonce } from "@ngrok/app-server/client";
|
|
403
|
+
|
|
404
|
+
export function Layout({ children }: { children: React.ReactNode }) {
|
|
405
|
+
const nonce = cspNonce();
|
|
406
|
+
return (
|
|
407
|
+
<html lang="en">
|
|
408
|
+
<head>
|
|
409
|
+
<Meta />
|
|
410
|
+
<Links nonce={nonce} />
|
|
411
|
+
</head>
|
|
412
|
+
<body>
|
|
413
|
+
{children}
|
|
414
|
+
<ScrollRestoration nonce={nonce} />
|
|
415
|
+
<Scripts nonce={nonce} />
|
|
416
|
+
</body>
|
|
417
|
+
</html>
|
|
418
|
+
);
|
|
419
|
+
}
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
In TanStack Start, give it to the router. `getRouter` runs on the server and in the browser:
|
|
423
|
+
|
|
424
|
+
```ts
|
|
425
|
+
import { cspNonce } from "@ngrok/app-server/client";
|
|
426
|
+
|
|
427
|
+
export function getRouter() {
|
|
428
|
+
return createRouter({ routeTree, ssr: { nonce: cspNonce() } });
|
|
429
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
## Deploys and open tabs
|
|
433
|
+
|
|
434
|
+
After a deploy, an open tab still runs the old build. Two things can then go wrong:
|
|
435
|
+
|
|
436
|
+
- **Old assets.** The tab asks for a chunk of its own build, such as `/assets/route-3f9a1c.js`, and the new server does not have it. Keep the `/assets/*` files of each build, with their `.<file>.gz` and `.<file>.br` copies, in storage that a deploy never deletes, such as an object store behind the CDN. File names are content hashes, so the builds never collide. The server sends `Cache-Control: no-store` with a missing asset, so a CDN does not keep the 404.
|
|
437
|
+
- **New data for old code.** The router fetches data from the new server, such as a React Router `.data` file or a TanStack Start server function, and the old code renders it. A changed loader can break the page.
|
|
438
|
+
|
|
439
|
+
`buildId()` and the client module fix the second problem at the next navigation, and the page that the visitor reads never reloads. For React Router, create the module once, and give its three hooks to the router:
|
|
440
|
+
|
|
441
|
+
```ts
|
|
442
|
+
// app/stale-build.ts (React Router)
|
|
443
|
+
import { staleBuildReactRouter } from "@ngrok/app-server/client";
|
|
444
|
+
|
|
445
|
+
export const staleBuild = staleBuildReactRouter({
|
|
446
|
+
onNewBuild: (build) => datadogRum.addAction("new build", { build }),
|
|
447
|
+
});
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
```tsx
|
|
451
|
+
// app/root.tsx
|
|
452
|
+
export const clientMiddleware = [staleBuild.middleware];
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
```tsx
|
|
456
|
+
// app/entry.client.tsx
|
|
457
|
+
startTransition(() => {
|
|
458
|
+
hydrateRoot(
|
|
459
|
+
document,
|
|
460
|
+
<HydratedRouter
|
|
461
|
+
unstable_fetch={staleBuild.fetch}
|
|
462
|
+
instrumentations={[staleBuild.instrumentation]}
|
|
463
|
+
/>,
|
|
464
|
+
);
|
|
465
|
+
});
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
For TanStack Start, give it the router, on the client only:
|
|
469
|
+
|
|
470
|
+
```tsx
|
|
471
|
+
// src/router.tsx (TanStack Start)
|
|
472
|
+
import { staleBuildTanStack } from "@ngrok/app-server/client";
|
|
473
|
+
|
|
474
|
+
export function getRouter() {
|
|
475
|
+
const router = createRouter({ routeTree });
|
|
476
|
+
if (!router.isServer) {
|
|
477
|
+
staleBuildTanStack(router);
|
|
478
|
+
}
|
|
479
|
+
return router;
|
|
480
|
+
}
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
The server needs no code: `defaultPlugins()` runs `buildId()` with the ID of the client build.
|
|
484
|
+
|
|
485
|
+
- After the client build, the `appServer` Vite plugin hashes the name and the content of each file of the client bundle. After the server build, it adds each file that the server build wrote to the client's assets directory, such as the React Router route manifest. It writes the hash as `buildId` in `.app-server.json`. The ID changes when the code or the routes that an open tab runs change. A deploy that changes only the server, a `public/` file, or a prerendered page keeps the ID, so an open tab does not move for nothing.
|
|
486
|
+
- To send another ID, such as the image tag, set `value`. With no value, such as an unset or empty variable, the server sends the build's ID:
|
|
487
|
+
|
|
488
|
+
```ts
|
|
489
|
+
// server.ts
|
|
490
|
+
defaultPlugins({ buildId: { value: process.env.IMAGE_TAG } });
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
- In development, the server sends no build ID unless `value` is set, because Vite's hot module replacement (HMR) updates an open tab after each edit.
|
|
494
|
+
- A build with no `appServer` Vite plugin has no ID. Set `value` for it.
|
|
495
|
+
- `buildId()` sends the build on each document and data response, as `X-Build-Id` and in `Server-Timing`.
|
|
496
|
+
- The module reads the build from the responses that the router fetches, and from the responses of this origin that the browser fetches with no script, such as a `<Link prefetch="intent">` hover. A prefetch can show a new build before the click. A build from another origin does not count.
|
|
497
|
+
- The router tells the module when a navigation starts, after its blockers. So a canceled link, `navigate()`, a form, a history step, and `blocker.proceed()` each act as the router acts.
|
|
498
|
+
- If a data request of a navigation gets a response from a new build, the browser loads the target URL as a document. The old code never gets the new data.
|
|
499
|
+
- If the tab already knows of a new build, the next navigation loads its target as a document before the old code renders it. With React Router, the root middleware does this for each `navigate` call, also to a route with no loader, and the router sends no data request. TanStack Router does this for each navigation to a new path or query, and clears its cache first, so the old code never renders the data of a preload.
|
|
500
|
+
- The document load keeps the URL fragment, such as `#usage`, and a replace navigation stays a replace.
|
|
501
|
+
- A revalidation, a fetcher, an action, the loaders after an action, and a request outside a navigation get their response, and only mark the tab. The page that the visitor reads never reloads, and a form keeps its result.
|
|
502
|
+
- A change to the fragment stays in the page.
|
|
503
|
+
- `onNewBuild(served)` runs once, when the tab first sees another build. Use it to count stale tabs in the app's RUM tool.
|
|
504
|
+
- `app/root.tsx` also runs on the server. The module reads no browser state until React Router calls it.
|
|
505
|
+
- With React Router, a history step to a route with no loader stays on the old build. The next link moves the tab.
|
|
506
|
+
- `unstable_fetch` is an experimental React Router prop, and the middleware reads `unstable_initiator` and `unstable_navigationType` from its arguments. React Router can change them.
|
|
507
|
+
|
|
508
|
+
The module sees a build only in a response from this server. By default, that is a document, a data request of the router, or a route discovery request. An app that loads its data in the browser, such as with TanStack Query, sends few of those. Send its queries through proxy routes on this server, as the next section shows, and each query also carries the build. A request that goes to another service directly carries no build, and that service must stay compatible with old clients.
|
|
509
|
+
|
|
510
|
+
### Proxy routes
|
|
511
|
+
|
|
512
|
+
A proxy route on this server forwards a request from the browser to the app's API, such as `/api/*`. The request makes the round trip anyway, so its response can carry the build at no cost. Add the routes to `paths`:
|
|
513
|
+
|
|
514
|
+
```ts
|
|
515
|
+
// server.ts
|
|
516
|
+
const app = createServer({
|
|
517
|
+
plugins: defaultPlugins({ buildId: { paths: (path) => path.startsWith("/api/") } }),
|
|
518
|
+
});
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
- The proxy route does not change. It can be a Hono route in `server.ts` or a React Router resource route.
|
|
522
|
+
- Each query and mutation through the route now tells the tab about a new build, so a tab finds a deploy at its next request, and moves to the new build at its next navigation.
|
|
523
|
+
- The tab never reloads the page that the visitor reads. A query that finds a new build only marks the tab.
|
|
524
|
+
- The response carries the build in `Server-Timing` only, with no `X-Build-Id`. The client reads it from resource timing, so a fetch client that keeps its own copy of `fetch` still reports the build. `staleBuildTanStack()` also reads it from each `fetch` response, so a loader that gets the new build's data in a navigation loads the page as a document.
|
|
525
|
+
- `buildId()` removes the `X-Build-Id` header and the `build` metric of the upstream API from each response, so the client reads only this app's build.
|
|
526
|
+
- A response that a cache can use again without the server gets no build, so a cached copy never reports an old build. That is a response with `public`, a `max-age`, an `s-maxage`, a stale time, a future `Expires`, or a `Last-Modified`, and with no `no-cache` or `no-store`.
|
|
527
|
+
|
|
528
|
+
The client module sends no request of its own and adds no wait. A client navigation makes the same requests with it as without it. It reads the build from the responses that the router already fetches. After a deploy, one navigation loads its target as a document: at most one more request, once for each deploy. Polling the server or checking the build before each navigation would add a round trip to every navigation. See [add no round trips to a client navigation](./docs/principles/no-added-round-trips.md).
|
|
529
|
+
|
|
530
|
+
## Trailing slashes
|
|
531
|
+
|
|
532
|
+
`/docs/button` and `/docs/button/` are two URLs. Choose one form for the site, and send a permanent redirect from the other form. Else a search engine and a cache keep two copies of each page. Point the canonical tag at the same form.
|
|
533
|
+
|
|
534
|
+
`defaultPlugins({ trailingSlash })` sets the form. The default is `never`:
|
|
535
|
+
|
|
536
|
+
| Mode | `/docs/button` | `/docs/button/` |
|
|
537
|
+
| ---------- | ---------------------- | --------------------- |
|
|
538
|
+
| `never` | 200 | 308 to `/docs/button` |
|
|
539
|
+
| `always` | 308 to `/docs/button/` | 200 |
|
|
540
|
+
| `preserve` | 200 | 200 |
|
|
541
|
+
|
|
542
|
+
The redirect applies to rendered and prerendered pages, and it keeps the query string. It does not apply to `/`, a method other than GET or HEAD, a data request of the framework, or a path that one of the app's own Hono routes matches, such as `app.get("/api/status")`. `always` adds no slash to a file in the client build, such as `/LICENSE`, or to a path whose last segment has a dot, such as `/llms.txt` or a `.data` request. React Router's route discovery manifest (`/__manifest`) counts as a data request.
|
|
543
|
+
|
|
544
|
+
Why 308: it is permanent, as 301 is, and a client keeps the method. Next.js and Vercel send the same status for this redirect.
|
|
545
|
+
|
|
546
|
+
### React Router
|
|
547
|
+
|
|
548
|
+
React Router has no trailing-slash option. It renders `/docs/button`, `/docs/button/`, and `/docs/button//` with a 200. So the server is the only place that makes the URL canonical. Choose the mode in `defaultPlugins`.
|
|
549
|
+
|
|
550
|
+
### TanStack Start
|
|
551
|
+
|
|
552
|
+
The TanStack router has its own `trailingSlash` option, and its default is also `never`. On the server it sends a 307 to its own form. Do not mix the two modes. When the server mode and the router mode differ, the redirects loop: the server sends `/x` to `/x/`, and the router sends `/x/` back to `/x`.
|
|
553
|
+
|
|
554
|
+
Check the server mode against the router with `RouterTrailingSlash`. It is the mode of the router in the app's `Register`, so TypeScript fails when the modes differ:
|
|
555
|
+
|
|
556
|
+
```ts
|
|
557
|
+
// src/router.ts
|
|
558
|
+
export function getRouter() {
|
|
559
|
+
return createRouter({ routeTree, trailingSlash: "always" });
|
|
560
|
+
}
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
```ts
|
|
564
|
+
// server.ts
|
|
565
|
+
import { createServer, defaultPlugins } from "@ngrok/app-server";
|
|
566
|
+
import type { RouterTrailingSlash } from "@ngrok/app-server/tanstack-start";
|
|
567
|
+
|
|
568
|
+
createServer({
|
|
569
|
+
plugins: defaultPlugins({ trailingSlash: "always" satisfies RouterTrailingSlash }),
|
|
570
|
+
});
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
`"never" satisfies RouterTrailingSlash` fails to type-check here. With no registered router, `RouterTrailingSlash` allows each mode. The server mode wins for each page, because the server redirects first. The router's 307 is temporary, and its `Location` uses the request's host, so a proxy's internal host can leak into it.
|
|
574
|
+
|
|
575
|
+
## Redirects
|
|
576
|
+
|
|
577
|
+
A site that moves pages sends a permanent redirect from each old URL. `defaultPlugins({ redirects })` takes a table:
|
|
578
|
+
|
|
579
|
+
```ts
|
|
580
|
+
defaultPlugins({
|
|
581
|
+
redirects: [
|
|
582
|
+
{ from: "/pricing-old", to: "/pricing" },
|
|
583
|
+
{ from: "/blog/:slug", to: "/articles/:slug" },
|
|
584
|
+
{ from: "/docs/*", to: "https://docs.example.com/*", status: 308 },
|
|
585
|
+
],
|
|
586
|
+
});
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
- A `:name` segment matches one path segment. A `*` last segment matches the rest of the path, or nothing, so `/docs/*` also matches `/docs`. The target can use each of them. An absolute target is percent-encoded as UTF-8. In the query of the target, a value gets `&`, `=`, and `+` encoded, so it stays one value.
|
|
590
|
+
- The status is 301 by default, or 308 to keep the method. The redirect keeps the query string, and puts it before the fragment of the target. It applies to GET and HEAD only.
|
|
591
|
+
- The first rule that matches wins. A trailing slash does not change the match. The table runs before `trailingSlash`, so `/pricing-old/` gets one redirect to `/pricing`. In the `never` mode, a local target loses its trailing slash, so `trailingSlash` does not redirect it again.
|
|
592
|
+
- The rules compile at startup. A rule that is not valid stops startup. A local target must be a safe local path, and an absolute target must keep the origin that its rule names. A request whose values break either check gets no redirect.
|
|
593
|
+
- A request that is already at the target of its rule gets no redirect, so `{ from: "/tags/:tag", to: "/tags/:tag/" }` with `trailingSlash: "always"` does not loop.
|
|
594
|
+
|
|
595
|
+
### Preview deploys
|
|
596
|
+
|
|
597
|
+
`noindex()` sets `X-Robots-Tag: noindex, nofollow` on each response, prerendered pages included, so a search engine does not index a preview deploy. Turn it on from the environment:
|
|
598
|
+
|
|
599
|
+
```ts
|
|
600
|
+
defaultPlugins({ noindex: process.env.PREVIEW === "1" });
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
## Content negotiation
|
|
604
|
+
|
|
605
|
+
One URL can answer HTML to a browser and markdown to an agent, per [acceptmarkdown.com](https://acceptmarkdown.com). `prefersMarkdown(request)` decides which answer a request gets. Use it in the server, in a plugin, and in the app, so each place answers one request the same way.
|
|
606
|
+
|
|
607
|
+
```ts
|
|
608
|
+
import { prefersMarkdown } from "@ngrok/app-server";
|
|
609
|
+
|
|
610
|
+
prefersMarkdown(new Request(url, { headers: { Accept: "text/markdown" } })); // => true
|
|
611
|
+
prefersMarkdown(new Request(url, { headers: { Accept: "text/html, text/markdown;q=0.5" } })); // => false
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
It returns `true` when these conditions are all true:
|
|
615
|
+
|
|
616
|
+
- The `Accept` header names `text/markdown`. A wildcard (`*/*`, `text/*`) never selects markdown, so a browser gets HTML.
|
|
617
|
+
- The `q` of `text/markdown` is more than 0.
|
|
618
|
+
- The `q` of `text/markdown` is equal to or more than the `q` of HTML. The `q` of HTML comes from the most specific range: `text/html`, then `text/*`, then `*/*`. A tie selects markdown.
|
|
619
|
+
- Both answers are UTF-8. A range with `charset=utf-8` wins over the same type with no charset, and a range with another charset does not match.
|
|
620
|
+
|
|
621
|
+
When a URL has both answers, follow these rules:
|
|
622
|
+
|
|
623
|
+
- Send `Vary: Accept` on both answers. Else a shared cache can give the markdown to a browser.
|
|
624
|
+
- Send no `Vary: Accept` for a URL with only one answer, such as the `.md` URL itself.
|
|
625
|
+
- Send the markdown with `Content-Type: text/markdown; charset=utf-8`.
|
|
626
|
+
- If the markdown also has its own URL, send `Link: <url>; rel="alternate"; type="text/markdown"` with the HTML, so a client that does not ask for markdown can find it.
|
|
627
|
+
|
|
628
|
+
### A prerendered markdown twin
|
|
629
|
+
|
|
630
|
+
When the build prerenders a markdown twin for each page, such as `/components/button.md` for `/components/button`, turn on `markdownTwins`:
|
|
631
|
+
|
|
632
|
+
```ts
|
|
633
|
+
createServer({ plugins: defaultPlugins({ prerendered: { markdownTwins: true } }) });
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
- A request that `prefersMarkdown` accepts gets the twin, with the twin's captured headers.
|
|
637
|
+
- Each answer for a page with a twin gets `Vary: Accept`: the twin, the prerendered HTML, and the framework's answer for a rendered page. The server adds `Accept` to the `Vary` values that are already there.
|
|
638
|
+
- Each answer for a page with a twin, except the twin, gets `Link: </components/button.md>; rel="alternate"; type="text/markdown"`, so a client can find the twin.
|
|
639
|
+
- A page with no twin, and the twin's own URL, get no `Vary: Accept` and no `Link`.
|
|
640
|
+
- In development, the client build has no twins. A request that `prefersMarkdown` accepts gets the framework's answer for the twin's URL, so an edit to the twin's route shows at the next request. If that answer is an error, such as a 404, or is not markdown, the request gets the HTML. A 304 stays a 304. A browser's answer gets no `Vary: Accept` and no `Link`, because the server does not ask the framework for a twin that it does not send.
|
|
641
|
+
- In development, React Router gives only the twins in its `prerender` config, as the build does. TanStack Start finds its prerendered pages only during the build, so in development each twin route that answers markdown counts.
|
|
642
|
+
- A plugin after `prerendered` does not see a twin, in development or in production, because a twin is a prerendered file. Put an auth check for a twin in `beforeStatic` or in the twin's route.
|
|
643
|
+
|
|
644
|
+
The default twin is the path with no trailing slash plus `.md`, and `/index.md` for `/`. A different mapping goes in `twinOf`. Its path follows the same rules as a request path:
|
|
645
|
+
|
|
646
|
+
```ts
|
|
647
|
+
prerendered({ markdownTwins: { twinOf: (path) => (path === "/" ? "/llms.md" : `${path}.md`) } });
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
`twinOf` also gets the request's Hono context, the same as `rewrite`. If it gives `undefined`, the request gets no twin, `rewrite` runs, and the answer gets no `Vary: Accept` and no `Link`. For example, when the framework renders a page for each query, keep a request with a query off the prerendered twin:
|
|
651
|
+
|
|
652
|
+
```ts
|
|
653
|
+
prerendered({
|
|
654
|
+
markdownTwins: {
|
|
655
|
+
twinOf: (path, c) =>
|
|
656
|
+
new URL(c.req.url).search === "" ? `${path === "/" ? "/index" : path}.md` : undefined,
|
|
657
|
+
},
|
|
658
|
+
});
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
The framework makes the twins. In React Router, one splat resource route can answer every twin. Prerender each twin URL, and point `twinOf` at the route. `markdownFor` stands for the app's own lookup:
|
|
662
|
+
|
|
663
|
+
```ts
|
|
664
|
+
// app/routes.ts
|
|
665
|
+
route("markdown/*", "routes/markdown.ts");
|
|
666
|
+
|
|
667
|
+
// app/routes/markdown.ts
|
|
668
|
+
export async function loader({ params }: Route.LoaderArgs) {
|
|
669
|
+
const markdown = await markdownFor(params["*"]); // "docs/button.md"
|
|
670
|
+
if (markdown == null) {
|
|
671
|
+
throw new Response("Not Found", { status: 404 });
|
|
672
|
+
}
|
|
673
|
+
return new Response(markdown, { headers: { "Content-Type": "text/markdown; charset=utf-8" } });
|
|
674
|
+
}
|
|
675
|
+
|
|
676
|
+
// react-router.config.ts
|
|
677
|
+
export default { prerender: ["/docs/button", "/markdown/docs/button.md"] };
|
|
678
|
+
|
|
679
|
+
// server.ts
|
|
680
|
+
const twinOf = (path: string) => `/markdown${path === "/" ? "/index" : path}.md`;
|
|
681
|
+
createServer({ plugins: defaultPlugins({ prerendered: { markdownTwins: { twinOf } } }) });
|
|
682
|
+
```
|
|
683
|
+
|
|
684
|
+
The same route answers the twins in development.
|
|
685
|
+
|
|
686
|
+
For other negotiation, `rewrite` maps a request path to the file to serve. It does not run for a request that gets the twin. To keep a request off the twin, give `undefined` from `twinOf`. When its answer depends on a request header, add a `Vary` for that header in a plugin.
|
|
687
|
+
|
|
688
|
+
### A rendered page
|
|
689
|
+
|
|
690
|
+
A page that the framework renders for each request negotiates in the app. In React Router, do it in `handleRequest` in `app/entry.server.tsx`. `markdownFor` stands for the app's own lookup:
|
|
691
|
+
|
|
692
|
+
```ts
|
|
693
|
+
import { prefersMarkdown } from "@ngrok/app-server";
|
|
694
|
+
|
|
695
|
+
export default async function handleRequest(
|
|
696
|
+
request: Request,
|
|
697
|
+
status: number,
|
|
698
|
+
headers: Headers /* , … */,
|
|
699
|
+
) {
|
|
700
|
+
const markdown = markdownFor(new URL(request.url).pathname);
|
|
701
|
+
if (markdown != null) {
|
|
702
|
+
headers.append("Vary", "Accept");
|
|
703
|
+
if (prefersMarkdown(request)) {
|
|
704
|
+
headers.set("Content-Type", "text/markdown; charset=utf-8");
|
|
705
|
+
return new Response(markdown, { status, headers });
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
// Render the HTML as usual. The `Vary` header goes with it.
|
|
709
|
+
}
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
A resource route, or a TanStack Start server route, gets the same `Request`. Call `prefersMarkdown(request)` there.
|
|
188
713
|
|
|
189
714
|
## Prerendered headers
|
|
190
715
|
|
|
191
716
|
During the framework's prerender pass, `appServer` records each prerendered path and the response headers of each prerendered file that is not an HTML document into `.app-server.json` in the client build. `prerendered()` replays the headers. It leaves out `Set-Cookie`, `Vary`, and the headers of one transfer, such as `Content-Length`. When the framework does not list its prerendered paths, as with TanStack Start, the server reads them from this file.
|
|
192
717
|
|
|
193
|
-
A document's headers are not recorded, because the framework sets them for each request (a CSP nonce, the host). Set the headers of a prerendered page with the `headers` option or a plugin.
|
|
718
|
+
A document's headers are not recorded, because the framework sets them for each request (a CSP nonce, the host). Set the headers of a prerendered page with the `headers` option or a plugin. The file also records the hash of each inline script of each HTML file in the client build, so `contentSecurityPolicy()` can give a prerendered page a CSP. See [A CSP for each document](#a-csp-for-each-document). It also holds the build ID. See [Deploys and open tabs](#deploys-and-open-tabs).
|
|
194
719
|
|
|
195
720
|
## Logs
|
|
196
721
|
|
|
@@ -204,7 +729,7 @@ createServer({
|
|
|
204
729
|
});
|
|
205
730
|
```
|
|
206
731
|
|
|
207
|
-
The default is `jsonSink()`: one JSON object per line on stdout.
|
|
732
|
+
The default is `jsonSink()`: one JSON object per line on standard output (stdout). It writes the lines of one event-loop turn in one write, at the end of the turn. Each line still reaches stdout before the process exits, and before the vercel handler returns.
|
|
208
733
|
|
|
209
734
|
In server code, read the request ID and a logger whose lines carry it. `requestContext()` works with each framework. It gives `undefined` outside a server request, such as in a prerender pass:
|
|
210
735
|
|
|
@@ -226,9 +751,52 @@ export async function loader({ context }: Route.LoaderArgs) {
|
|
|
226
751
|
}
|
|
227
752
|
```
|
|
228
753
|
|
|
754
|
+
A request with a valid W3C `traceparent` header logs `trace_id` and `span_id` on each line. `requestId({ datadogTraceIds: true })` also logs `dd.trace_id` and `dd.span_id`, the lower 64 bits in decimal, so Datadog connects each line to its trace.
|
|
755
|
+
|
|
756
|
+
`accessLog({ attributes })` adds the app's own attributes to each request line. The callback runs when the line goes out. It gets the context and what went out: `status`, `headers`, `bytes`, and `aborted`. Read a response header from `sent.headers`, not from `c.res`: `sent.headers` has the headers that went out on each runtime, after the header hooks, and `c.res` can lack them. On Node.js and Vercel, `sent.headers` also has the headers that the listener adds, such as `Content-Length`. `accessLog({ serverTiming: true })` sets `Server-Timing: app;dur=<ms>` on each HTML document: the time until the response headers were ready.
|
|
757
|
+
|
|
758
|
+
```ts
|
|
759
|
+
defaultPlugins({
|
|
760
|
+
requestId: { datadogTraceIds: true },
|
|
761
|
+
accessLog: {
|
|
762
|
+
attributes: (c, sent) => ({
|
|
763
|
+
"usr.id": c.get("userId"),
|
|
764
|
+
"http.response.cache_control": sent.headers.get("Cache-Control"),
|
|
765
|
+
}),
|
|
766
|
+
},
|
|
767
|
+
});
|
|
768
|
+
```
|
|
769
|
+
|
|
770
|
+
## Health checks
|
|
771
|
+
|
|
772
|
+
`health()` answers `/livez` and `/readyz` with `Cache-Control: no-store`. `/livez` always answers 200. `/readyz` answers 200 until the server gets a stop signal, then 503. `ready` adds an app check, such as a database ping. When the check starts to fail, one warn line goes to the log, and when it passes again, one info line. A stop signal during the check also gives 503. `defaultPlugins()` runs `health()` first, so a probe skips the access log. Its `health` option takes the options of `health()`:
|
|
773
|
+
|
|
774
|
+
```ts
|
|
775
|
+
export default createServer({
|
|
776
|
+
plugins: defaultPlugins({ health: { ready: async () => db.ping() } }),
|
|
777
|
+
shutdownDelayMs: 5_000,
|
|
778
|
+
});
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
`livePath` and `readyPath` move the probes. `defaultPlugins({ health: false })` turns them off, such as for an app with its own `/livez` route.
|
|
782
|
+
|
|
783
|
+
On a stop signal, a load balancer removes the server some seconds later. Without a delay, the requests that it sends in that time fail. With `shutdownDelayMs`, the server answers 503 on `/readyz` and serves the other requests for that time. Then it drains. In Kubernetes, set `terminationGracePeriodSeconds` to more than the delay plus `shutdownDeadlineMs`:
|
|
784
|
+
|
|
785
|
+
```yaml
|
|
786
|
+
spec:
|
|
787
|
+
terminationGracePeriodSeconds: 20 # 5 s delay + 10 s drain + margin
|
|
788
|
+
containers:
|
|
789
|
+
- name: app
|
|
790
|
+
readinessProbe:
|
|
791
|
+
httpGet: { path: /readyz, port: 3000 }
|
|
792
|
+
periodSeconds: 2
|
|
793
|
+
livenessProbe:
|
|
794
|
+
httpGet: { path: /livez, port: 3000 }
|
|
795
|
+
```
|
|
796
|
+
|
|
229
797
|
## Environment
|
|
230
798
|
|
|
231
|
-
`runtimeEnv(schema)` validates the environment once, at startup, with any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype). A bad value stops the server with a message that names it.
|
|
799
|
+
`runtimeEnv(schema)` validates the environment once, at startup, with any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype). A bad value stops the server with a message that names it. Give the plugin to the `env` option of `defaultPlugins()`.
|
|
232
800
|
|
|
233
801
|
```ts
|
|
234
802
|
import { createServer, defaultPlugins, runtimeEnv } from "@ngrok/app-server";
|
|
@@ -238,7 +806,7 @@ export const env = runtimeEnv(
|
|
|
238
806
|
z.object({ PUBLIC_API_URL: z.url(), SESSION_KEY: z.string().min(32) }),
|
|
239
807
|
);
|
|
240
808
|
|
|
241
|
-
export default createServer({ plugins: defaultPlugins({
|
|
809
|
+
export default createServer({ plugins: defaultPlugins({ env }) });
|
|
242
810
|
```
|
|
243
811
|
|
|
244
812
|
The values whose names start with `PUBLIC_` go into each HTML document at serve time, prerendered pages included, so one build serves every environment. Read them in the browser:
|
|
@@ -247,6 +815,8 @@ The values whose names start with `PUBLIC_` go into each HTML document at serve
|
|
|
247
815
|
const publicEnv = JSON.parse(document.getElementById("app-server-public-env")?.textContent ?? "{}");
|
|
248
816
|
```
|
|
249
817
|
|
|
818
|
+
When there are public values, the server sends each prerendered page from its file, not from its compressed copy, because the values change the bytes of the page. `streamingCompress()` then gzips the page for each request.
|
|
819
|
+
|
|
250
820
|
## Long-lived responses
|
|
251
821
|
|
|
252
822
|
`eventStream()` makes a server-sent event response that sends a heartbeat every 15 s, stops when the client disconnects, and closes at shutdown so the drain does not wait for it:
|
|
@@ -271,8 +841,9 @@ A framework adapter or a host adapter is two small objects. A third-party adapte
|
|
|
271
841
|
|
|
272
842
|
- `FrameworkBuild` (from `@ngrok/app-server/vite`): the framework's server module, the module of the run side, how to detect the prerender pass, and a check of the Vite config.
|
|
273
843
|
- `FrameworkRuntime` (from `@ngrok/app-server`): `fetch(request, context)`, plus, when the framework has them, its client build, its prerendered paths, its data requests, and the content types that `mime` lacks. The run-side module exports `runtime(serverModule, { mode })`.
|
|
274
|
-
- `HostBuild` (from `@ngrok/app-server/vite`): the module of the run side
|
|
275
|
-
- `HostRuntime` (from `@ngrok/app-server`): the client build's files, the default listeners, request storage for `requestContext()`, a gzip stream, and a lifecycle for a long-lived process. The run-side module exports `host`.
|
|
844
|
+
- `HostBuild` (from `@ngrok/app-server/vite`): the module of the run side, the file name of the server entry, and an optional `output` that writes the host's deploy output after the build, such as `.vercel/output`.
|
|
845
|
+
- `HostRuntime` (from `@ngrok/app-server`): the client build's files, the default listeners (a serverless host has none), request storage for `requestContext()`, a gzip stream, and a lifecycle for a long-lived process. The run-side module exports `host`. `files(...).open(path, range)` must honor `range`, because the static stages send those bytes in a 206. An optional `files(...).snapshot()` lists the client build once. The production server calls it at start, answers each lookup from that list, and keeps each file up to 256 KiB in memory after the first read, up to 32 MiB in all. The `.<file>.gz` and `.<file>.br` copies count in that limit. A client that accepts brotli reads only the `.br` copies, so the copies make the memory that a site needs smaller. If clients read each file in all three forms, a large site can need more than 32 MiB. Then the files that the server reads last stream from disk. Restart the server after you change the client build. A file that you remove while it runs gets a 500, unless it is in memory.
|
|
846
|
+
- `ResponseEdge` (from `@ngrok/app-server`): for a listener that writes each response itself. The listener makes one for each request and gives it as the `edge` binding. The server runs the header hooks on a list of the headers and keeps the list in the edge, so it copies no response for them. The listener writes `edge.headersFor(response)` in place of the headers of the response, adds each body byte to `edge.bytes`, gives an error that stops the response to `edge.fail`, and calls `edge.close(status, aborted, head)` once, with the status and the header list that it sent. The access log takes its line from that report. Only the first request that gets an edge uses it: a request that the app sends through itself again with `c.env` changes its own response. The node host's listener on Node.js and the vercel handler give one. Without it, as on Bun and Deno, the server makes one new response with the headers after the hooks and a body that counts its bytes.
|
|
276
847
|
|
|
277
848
|
## Options
|
|
278
849
|
|
|
@@ -281,12 +852,16 @@ A framework adapter or a host adapter is two small objects. A third-party adapte
|
|
|
281
852
|
- `plugins`: default `defaultPlugins()`.
|
|
282
853
|
- `logger`: default `jsonSink()`.
|
|
283
854
|
- `listeners`: default the host's listeners. A listener decides how connections arrive. On the node host, the default is `[tcp()]` from `@ngrok/app-server/node`. `tcp()` uses `node:http`, `Bun.serve`, or `Deno.serve`.
|
|
284
|
-
- `trustForwardedProto`: read the scheme from `X-Forwarded-Proto`. Set it only behind a proxy that overwrites the header. Default `false`. For a build with no `server.ts`, set `TRUST_FORWARDED_PROTO=1`. TanStack Start compares a server function call's `Origin` with the request URL when the browser sends no `Sec-Fetch-Site`, so set this option behind a proxy that ends TLS.
|
|
285
|
-
- `
|
|
855
|
+
- `trustForwardedProto`: read the scheme from `X-Forwarded-Proto`. Set it only behind a proxy that overwrites the header. Default `false`. The server passes it to each listener as `start(fetch, { trustForwardedProto })`, so the node listener on Node.js builds each request with that scheme and copies none. For a listener that ignores it, the server copies each request to change its scheme. For a build with no `server.ts`, set `TRUST_FORWARDED_PROTO=1`. TanStack Start compares a server function call's `Origin` with the request URL when the browser sends no `Sec-Fetch-Site`, so set this option behind a proxy that ends TLS.
|
|
856
|
+
- `trustedProxyHops`: how many proxies in front of the server add to `X-Forwarded-For`, such as `1` behind the ngrok edge. With N, the client address is the Nth address from the right of that header. The access log and `requestContext()?.clientAddress` use it. Default `0`, the address of the socket. Set it only to the number of proxies that you run, else a client can spoof its address. For a build with no `server.ts`, set `TRUSTED_PROXY_HOPS`.
|
|
857
|
+
- `shutdownDelayMs`: how long the listeners serve on after a stop signal, before the drain starts. See [Health checks](#health-checks). Default `0`.
|
|
858
|
+
- `shutdownDeadlineMs`: how long open requests get to finish after the drain starts. Default `10000`.
|
|
286
859
|
|
|
287
860
|
## Limits
|
|
288
861
|
|
|
289
862
|
- The build must serve at `/` (Vite `base`). The Vite plugin fails the build for another base.
|
|
290
863
|
- `appServer` does not support React Router `serverBundles`.
|
|
291
|
-
- The
|
|
864
|
+
- The server build holds one copy of each external package. If the build finds two copies of one external package, such as two versions, the build fails.
|
|
865
|
+
- One server process uses one CPU core. To use more cores, run one replica or one container for each core behind the load balancer.
|
|
866
|
+
- The package has two host adapters, `node` and `vercel`. Another host, such as Cloudflare Workers, needs its own adapter. See `HostRuntime` and `HostBuild`. A serverless host calls the `fetch` of the build's `appServer` export for each request. The build also exports `hostModule`, the host's run-side module, so a function file can call it through the bundle's copy.
|
|
292
867
|
- On Deno, `Deno.serve` logs a notice about its legacy `request.signal` behavior.
|