You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/adapters/build.md
+8-10Lines changed: 8 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,12 @@ outline: deep
4
4
5
5
# Build
6
6
7
-
Produces a self-contained static deploy of a devframe:
7
+
Produces a static deploy:
8
8
9
-
1. Copies the author's SPA dist (`clientAssets` or `options.distDir`) into `<outDir>`.
9
+
1. Copies the SPA dist into `<outDir>`.
10
10
2. Runs `setup(ctx)` with `mode: 'build'`.
11
-
3. Collects RPC dumps for every `'static'`function and any `'query'` function with `dump.inputs` / `snapshot: true`.
12
-
4. Writes `<outDir>/__connection.json` (`{ backend: 'static' }`) and sharded dump files under `<outDir>/__rpc-dump/` — both at the SPA root so the deployed client discovers them via relative paths from `document.baseURI`.
11
+
3. Collects RPC dumps for every `'static'` and `'query'` with `dump.inputs` / `snapshot: true`.
12
+
4. Writes `__connection.json` (`{ backend: 'static' }`) and sharded dumps under `__rpc-dump/`.
|`outDir`|`dist-static`| Output directory. Cleared on each build. |
26
-
|`distDir`|`def.clientAssets`(falls back to deprecated `def.cli?.distDir`) | Override the SPA dist directory (a local path or a [remote assets](/guide/client-assets) package, materialized in full at build time). |
27
-
|`pretty`|`false`| Pretty-print dump JSON (larger on disk). |
The resulting directory hosts on any static web server (`serve`, nginx, GitHub Pages, …). The client auto-detects `static` mode by resolving `./__connection.json` against `document.baseURI` and runs in read-only form.
30
-
31
-
`createBuild` copies the SPA verbatim, so deploying under a custom URL base just means building the SPA with relative asset paths (`vite.base: './'`) — the client discovers the effective base at runtime.
29
+
The client runs read-only. For a custom URL base, build with relative asset paths (`vite.base: './'`).
Copy file name to clipboardExpand all lines: docs/adapters/cac.md
+16-24Lines changed: 16 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,13 @@ outline: deep
4
4
5
5
# CLI (cac)
6
6
7
-
The cac adapter wraps a `DevframeDefinition` in a [`cac`](https://github.com/cacjs/cac)-powered command-line interface. From one entry it spins up an `h3` dev server with WebSocket RPC, builds static snapshots, or starts an MCP server.
8
-
9
-
`cac` is an optional peer dependency, pulled in only through this adapter — install it alongside `devframe` to opt into `createCac`:
7
+
A [`cac`](https://github.com/cacjs/cac) CLI around a `DevframeDefinition` with `dev`, `build`, and `mcp` commands. `cac` is an optional peer:
10
8
11
9
```sh
12
10
npm install devframe cac
13
11
```
14
12
15
-
Tools that assemble their own command-line shell from the [lower-level factories](#use-your-own-cli-framework)never import this adapter, so they run without`cac`.
13
+
The [lower-level factories](#use-your-own-cli-framework)need no`cac`.
Standalone CLI serves the SPA at `/`by default. The `/__devframe/`prefix is for *hosted* adapters where devframe mounts alongside an existing app — see [Mount paths](./#mount-paths).
37
+
The SPA serves at `/`standalone, `/__devframe/` hosted ([Mount paths](./#mount-paths)).
42
38
43
39
## Options
44
40
45
-
`createCac(def, options?)` accepts:
41
+
`createCac(def, options?)`:
46
42
47
43
| Option | Default | Description |
48
44
|--------|---------|-------------|
49
-
|`defaultPort`|`9999` (or `def.cli?.port`) |Port used by the dev command when `--port`isn't provided. |
50
-
|`configureCli`| — |`(cli: CAC) => void` — final hook to add commands/flags at the assembly stage, after the definition's `cli.configure` runs. |
51
-
|`onReady`| — |`(info: { origin, port, app }) => void \| Promise<void>` — called once the dev server is listening. Use this to print your own startup banner. |
45
+
|`defaultPort`|`9999` (or `def.cli?.port`) |Dev port if `--port`unset. |
The `cli` property lets the caller add ad-hoc commands and flags right before `parse()` when a `configureCli` callback is inconvenient.
63
-
64
58
## Definition-level `cli` fields
65
59
66
60
```ts
@@ -87,11 +81,11 @@ defineDevframe({
87
81
})
88
82
```
89
83
90
-
The top-level [`clientAssets`](/guide/client-assets) supplies the SPA the dev/build commands serve; everything under `cli` has sensible defaults. The `configure`hook runs *before*the `configureCli` option passed to `createCac`, so the final tool author always has the last word on flags.
Devframe leaves startup output to the application. Wire `onReady` to print your own banner:
88
+
Print a banner via `onReady`:
95
89
96
90
```ts
97
91
awaitcreateCac(devframe, {
@@ -101,17 +95,15 @@ await createCac(devframe, {
101
95
}).parse()
102
96
```
103
97
104
-
Structured diagnostics (via `nostics`) continue to surface through their normal reporters.
105
-
106
98
## Use your own CLI framework
107
99
108
-
To integrate devframe into an existing commander / yargs program — or to expose a different command structure than `createCac`'s `dev` / `build` / `mcp` triplet — drop down to the peer factories. Same `DevframeDefinition`, different shell:
100
+
Peer factories for a commander/yargs program:
109
101
110
102
| Building block | Entry | Purpose |
111
103
|----------------|-------|---------|
112
-
|[`createDevServer(def, opts?)`](./dev)|`devframe/adapters/dev`| h3 + WebSocket RPC + SPA mount |
Copy file name to clipboardExpand all lines: docs/adapters/dev.md
+18-31Lines changed: 18 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ outline: deep
4
4
5
5
# Dev
6
6
7
-
The `dev` adapter is the building block`createCac` uses internally — h3 + WebSocket RPC + the author's SPA mounted at the resolved base path. Reach for it directly to mount the dev server inside an existing CLI program (commander, yargs, hand-rolled CAC) or to attach custom middleware to the underlying h3 app.
7
+
`createCac`'s building block: h3 + WebSocket RPC + the SPA at the resolved base path.
`createDevServer` returns the underlying `StartedServer` (origin, port, h3 app, WS server, RPC group, `close()`) so callers can integrate it into their own process lifecycle.
|`port`| resolved via `resolveDevServerPort`|Port to listen on. |
28
-
|`flags`|`{}`|Parsed flag bag forwarded to`setup(ctx, { flags })`. |
29
-
|`distDir`|`def.clientAssets` (falls back to deprecated `def.cli?.distDir`) | SPA dist override. When unset the server runs in bridge mode (meta + WS only). |
30
-
|`basePath`|`resolveBasePath(def, 'standalone')`| Mount path override. |
31
-
|`app`| fresh h3 app |Pre-configured h3 app to mount onto (custom middleware, auth, extra static assets). |
32
-
|`openBrowser`| resolves from `flags.open` / `def.cli?.open`|Explicit on/off override. `false`disables; a string opens that relative path. |
33
-
|`ws`|`def.cli?.ws`|How the browser reaches the RPC WebSocket — see below. |
34
-
|`onReady`| — |Callback when the WS server is bound. |
27
+
|`port`| resolved via `resolveDevServerPort`|Listen port. |
28
+
|`flags`|`{}`|To`setup(ctx, { flags })`. |
29
+
|`distDir`|`def.clientAssets` (falls back to deprecated `def.cli?.distDir`) | SPA dist; unset = bridge mode. |
30
+
|`basePath`|`resolveBasePath(def, 'standalone')`| Mount override. |
31
+
|`app`| fresh h3 app |Mount onto. |
32
+
|`openBrowser`| resolves from `flags.open` / `def.cli?.open`|`false`off; string opens a path. |
33
+
|`ws`|`def.cli?.ws`| RPC WebSocket — see below. |
34
+
|`onReady`| — |WS-bind callback. |
35
35
36
36
## WebSocket endpoint
37
37
38
-
By default the RPC socket shares the HTTP server's port and binds to the `__ws` route next to `__connection.json`. The descriptor advertises a *relative* path, so the client connects to its own origin — the link follows the page through a reverse proxy that rewrites the domain, port, or subpath. Configure the three connection scenarios via `def.cli.ws` (or the `ws` call-site option):
39
-
40
-
```ts
41
-
defineDevframe({
42
-
// 1. Same server, a custom route (default route is `__ws`):
43
-
cli: { ws: { route: '__sockets' } },
44
-
45
-
// 2. A dedicated port on the same host:
46
-
cli: { ws: { port: 9788 } },
47
-
48
-
// 3. A remote, fully-qualified endpoint (e.g. a tunnel/relay):
Copy file name to clipboardExpand all lines: docs/adapters/embedded.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ outline: deep
4
4
5
5
# Embedded
6
6
7
-
Register a devframe into an already-running context at runtime. Mirrors the [`vite`](./vite) adapter's plugin-scan, but for callers that need dynamic, post-startup registration. The host decides the mount path; `embedded` is a hosted adapter and inherits the `/__<id>/` default when one is needed.
7
+
Register a devframe into an already-running context at runtime — dynamic, post-startup registration (unlike [`vite`](./vite)'s plugin-scan). Inherits the hosted `/__<id>/` default.
0 commit comments