@samebase/convex-hosting 0.13.1 → 0.14.0

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +72 -63
  3. package/package.json +6 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.14.0
4
+
5
+ - The README, which this package ships, starts with what the component is, who it is for, and the
6
+ quick start; the Cloudflare rules, the tests, and the comparisons with Workers and with
7
+ static-hosting have their own sections. It links the directory listing and carries its badge.
8
+ - Releases publish on merge with provenance; no staged approval.
9
+
3
10
  ## 0.13.1
4
11
 
5
12
  - `deploy --preview-name` without a deploy key, and without a login whose project is in
package/README.md CHANGED
@@ -1,38 +1,15 @@
1
1
  # Convex Hosting
2
2
 
3
- Serves a web app from the Convex deployment that runs its backend, at
4
- `https://<deployment>.convex.site`: the files of a build and the pages the app renders. One
5
- deployment, one URL, one deploy command.
3
+ [![Convex Component](https://www.convex.dev/components/badge/samebase/convex-hosting)](https://www.convex.dev/components/samebase/convex-hosting)
6
4
 
7
- The files follow
8
- [Cloudflare Workers rules](https://developers.cloudflare.com/workers/static-assets/). The serving
9
- code is Cloudflare's asset Worker, copied from
10
- [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk) at a pinned commit and run
11
- inside a Convex HTTP action, so `_headers`, `_redirects`, `.assetsignore`, `html_handling`, and
12
- `not_found_handling` mean what they mean on Cloudflare. This repository's CI runs Cloudflare's own
13
- tests against it: its
14
- [196 cases](https://github.com/samebase/convex-hosting/blob/main/packages/convex-hosting/src/component/conformance.test.ts)
15
- for `html_handling` and path encoding, and its
16
- [integration test](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting/src/workers-sdk/fixtures/workers-with-assets-only)
17
- for a files-only site, with its imports pointed at this package, on a local Convex deployment.
18
-
19
- An app that renders pages takes the place of the Worker script: an object with `fetch(request)` that
20
- answers what no file answers. TanStack Start has
21
- [an adapter](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting-tanstack-start),
22
- with streamed pages, server functions, server routes, request middleware, and cookie sessions. The
23
- [TanStack Start example](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr)
24
- is deployed here and, from the same source, as a real Worker; CI keeps the difference between the
25
- two to a committed patch.
5
+ A [Convex component](https://www.convex.dev/components/samebase/convex-hosting) that serves a web
6
+ app's built files and server-rendered pages from the deployment that runs its backend, at
7
+ `https://<deployment>.convex.site`.
26
8
 
27
- This package exists to run server-rendered frameworks on Convex, with Cloudflare's rules for the
28
- files; Convex's own static-hosting component serves files only
29
- ([how they differ](https://github.com/samebase/convex-hosting/blob/main/docs/from-static-hosting.md)).
30
- Use it when the backend is Convex and a second host for the frontend is one host too many. A Worker
31
- has what Convex does not: the data center nearest the visitor, Node's built-in modules, an edge
32
- cache, and WebSockets. The list, with numbers, is in
33
- [What differs from a Worker](https://github.com/samebase/convex-hosting/blob/main/docs/workers.md).
9
+ Use it when the backend is on Convex and the frontend should be served from the same deployment,
10
+ including a [TanStack Start](https://tanstack.com/start) app with server-side rendering.
34
11
 
35
- ## Use
12
+ ## Quick start
36
13
 
37
14
  Requires Node 22 or later and `convex` 1.46 or later.
38
15
 
@@ -71,14 +48,15 @@ export default http;
71
48
  Deploy:
72
49
 
73
50
  ```sh
74
- npx convex-hosting deploy --build "vite build" --dist dist --not-found-handling single-page-application
51
+ npx convex-hosting deploy --build "vite build" --dist dist
75
52
  ```
76
53
 
77
54
  It builds, uploads `dist`, pushes the functions, and prints
78
- `Deployed version <id> to https://<deployment>.convex.site.` A site with no build omits `--build`.
79
- Deploy production with this command, never with a plain `npx convex deploy`: a plain push names the
80
- version of this checkout's last deploy, often another deployment's, and the site answers 404 until
81
- the next `convex-hosting deploy`.
55
+ `Deployed version <id> to https://<deployment>.convex.site.` A site with no build omits `--build`; a
56
+ single-page app adds `--not-found-handling single-page-application`. Deploy production with this
57
+ command, never with a plain `npx convex deploy`: a plain push names the version of this checkout's
58
+ last deploy, often another deployment's, and the site answers 404 until the next
59
+ `convex-hosting deploy`.
82
60
 
83
61
  On a fresh clone, the first push of `npx convex dev` fails: `convex/http.ts` imports
84
62
  `.convex-hosting/version.js`, which only a deploy writes. `npx convex dev` keeps running after that
@@ -89,31 +67,19 @@ npx convex dev # creates your dev deployment and .env.local; keep it running
89
67
  ```
90
68
 
91
69
  ```sh
92
- npx convex-hosting deploy --dev --build "vite build" --dist dist --not-found-handling single-page-application
70
+ npx convex-hosting deploy --dev --build "vite build" --dist dist
93
71
  ```
94
72
 
95
73
  The deploy writes the version file and pushes; the watcher in the first terminal shows its error
96
74
  until the next change under `convex/`, and works as usual from then on.
97
75
 
98
- For pages rendered on the server, pass the app's server entry, the object with `fetch(request)`, as
99
- the fourth argument of `routeAll`. The
100
- [adapter](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting-tanstack-start)
101
- shows it for TanStack Start.
76
+ ## Server-rendered pages
102
77
 
103
- ## How a deploy switches the site
104
-
105
- On Cloudflare, `wrangler deploy` uploads the files and the Worker code as one version, so the switch
106
- is atomic. Here two systems hold the two halves: the component's storage holds the files, and
107
- `npx convex deploy` pushes the code. `deploy` binds them the same way. It uploads the files as a new
108
- version, writes that version's id to `.convex-hosting/version.js`, and then pushes the code, which
109
- imports the file and asks the component for exactly that version. The push is the switch: no pointer
110
- moves in a second step, so there is no moment when new code serves old files, and no page refers to
111
- a file that is not uploaded yet. The first request the new code serves marks its version live and
112
- deletes the versions that were live before it. A version whose push never came is deleted at a later
113
- switch, once it is a day old; nothing is deleted by the clock alone. The one rule: run one deploy at
114
- a time per deployment. The
115
- [design](https://github.com/samebase/convex-hosting/blob/main/docs/design.md#orderings-and-timing)
116
- works through every interleaving.
78
+ An app that renders pages passes its server entry as the fourth argument of `routeAll`. The entry
79
+ takes the place of a Worker script: an object with `fetch(request)` that answers what no file
80
+ answers. TanStack Start has
81
+ [an adapter](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting-tanstack-start),
82
+ with streamed pages, server functions, server routes, request middleware, and cookie sessions.
117
83
 
118
84
  ## Examples
119
85
 
@@ -129,9 +95,11 @@ works through every interleaving.
129
95
  - [tanstack-ssr](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr): pages
130
96
  rendered per request, with cookie sessions, live at
131
97
  [gallant-llama-40.convex.site](https://gallant-llama-40.convex.site). Its
132
- [Worker twin](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr-workers)
133
- is live at
134
- [convex-hosting-tanstack-ssr-workers.pfp.workers.dev](https://convex-hosting-tanstack-ssr-workers.pfp.workers.dev).
98
+ [Worker twin](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr-workers),
99
+ live at
100
+ [convex-hosting-tanstack-ssr-workers.pfp.workers.dev](https://convex-hosting-tanstack-ssr-workers.pfp.workers.dev),
101
+ is the same source deployed as a real Worker; CI keeps the difference between the two to a
102
+ [committed patch](https://github.com/samebase/convex-hosting/blob/main/examples/tanstack-ssr-workers.patch).
135
103
 
136
104
  ## Documentation
137
105
 
@@ -150,14 +118,55 @@ works through every interleaving.
150
118
  what it is.
151
119
  - [Changelog](https://github.com/samebase/convex-hosting/blob/main/packages/convex-hosting/CHANGELOG.md).
152
120
 
153
- ## Status
121
+ ## Compared with Cloudflare Workers
122
+
123
+ The files follow
124
+ [Cloudflare Workers rules](https://developers.cloudflare.com/workers/static-assets/). The serving
125
+ code is Cloudflare's asset Worker, copied from
126
+ [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk) at a pinned commit and run
127
+ inside a Convex HTTP action, so `_headers`, `_redirects`, `.assetsignore`, `html_handling`, and
128
+ `not_found_handling` mean what they mean on Cloudflare.
154
129
 
155
- Before 1.0: a minor release can change the API, and the changelog says what changed. It started from
156
- Convex's [static-hosting](https://github.com/convex/static-hosting) component and grew into a
157
- different design around Cloudflare's asset Worker;
130
+ This repository's CI runs Cloudflare's own tests against it: its
131
+ [196 cases](https://github.com/samebase/convex-hosting/blob/main/packages/convex-hosting/src/component/conformance.test.ts)
132
+ for `html_handling` and path encoding, and its
133
+ [integration test](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting/src/workers-sdk/fixtures/workers-with-assets-only)
134
+ for a files-only site, with its imports pointed at this package, on a local Convex deployment.
135
+
136
+ A Worker has what Convex does not: the data center nearest the visitor, Node's built-in modules, an
137
+ edge cache, and WebSockets.
138
+ [What differs from a Worker](https://github.com/samebase/convex-hosting/blob/main/docs/workers.md)
139
+ lists each difference, with numbers.
140
+
141
+ ## Compared with static-hosting
142
+
143
+ Convex's [static-hosting](https://github.com/convex/static-hosting) component serves the files of a
144
+ build. This package started from it and exists for frameworks that render pages on the server, which
145
+ needed a different serving model: Cloudflare's rules for the files, and a deploy that switches code
146
+ and files together.
158
147
  [From static-hosting](https://github.com/samebase/convex-hosting/blob/main/docs/from-static-hosting.md)
159
- lists what differs and how to move. The author's apps run on it, among them
160
- [Scout](https://github.com/samebase/scout) and [chessmerge.com](https://chessmerge.com).
148
+ lists what differs and how to move an app.
149
+
150
+ ## How a deploy switches the site
151
+
152
+ On Cloudflare, `wrangler deploy` uploads the files and the Worker code as one version, so the switch
153
+ is atomic. Here two systems hold the two halves: the component's storage holds the files, and
154
+ `npx convex deploy` pushes the code. `deploy` binds them the same way. It uploads the files as a new
155
+ version, writes that version's id to `.convex-hosting/version.js`, and then pushes the code, which
156
+ imports the file and asks the component for exactly that version. The push is the switch: no pointer
157
+ moves in a second step, so there is no moment when new code serves old files, and no page refers to
158
+ a file that is not uploaded yet. The first request the new code serves marks its version live and
159
+ deletes the versions that were live before it. A version whose push never came is deleted at a later
160
+ switch, once it is a day old; nothing is deleted by the clock alone. The one rule: run one deploy at
161
+ a time per deployment. The
162
+ [design](https://github.com/samebase/convex-hosting/blob/main/docs/design.md#orderings-and-timing)
163
+ works through every interleaving.
164
+
165
+ ## Status
166
+
167
+ Before 1.0: a minor release can change the API, and the changelog says what changed. The author's
168
+ apps run on it, among them [Scout](https://github.com/samebase/scout) and
169
+ [chessmerge.com](https://chessmerge.com).
161
170
 
162
171
  ## License
163
172
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@samebase/convex-hosting",
3
- "version": "0.13.1",
3
+ "version": "0.14.0",
4
4
  "description": "Serves a web app from its own Convex deployment: the files of a build, and the pages the app renders.",
5
5
  "keywords": [
6
6
  "component",
@@ -45,15 +45,15 @@
45
45
  },
46
46
  "dependencies": {
47
47
  "ignore": "7.0.12",
48
- "mime": "4.1.0",
49
- "zod": "4.6.5"
48
+ "mime": "4.1.1",
49
+ "zod": "4.6.6"
50
50
  },
51
51
  "devDependencies": {
52
- "@types/node": "24.19.1",
52
+ "@types/node": "24.19.2",
53
53
  "convex": "1.46.0",
54
- "convex-test": "0.0.60",
54
+ "convex-test": "0.0.61",
55
55
  "typescript": "7.0.2",
56
- "undici": "7.29.1",
56
+ "undici": "8.11.2",
57
57
  "vite-plus": "1.1.0"
58
58
  },
59
59
  "peerDependencies": {