Skip to content

Commit 02a87e6

Browse files
committed
chore(examples): rename hub examples to custom-hub-* and drop -minimal suffix
- hub-vite -> custom-hub-vite, hub-next -> custom-hub-next (full reference hosts) - hub-*-minimal -> hub-* (deno, fastify, hono, next, nitro, rsbuild, sveltekit, vite) - update package.json names/homepages and all references across docs, AGENTS.md, turbo.json, knip.jsonc, scripts, and tests
1 parent dcce1ca commit 02a87e6

142 files changed

Lines changed: 1646 additions & 1658 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

AGENTS.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
**`devframe`** is the framework-neutral container for one devtool integration, portable across hub UI providers. Build a single tool (its RPC, its SPA, its diagnostics, its CLI/build/embedded outputs) without caring how it'll be displayed. A devframe runs standalone (CLI, static deploy, embedded SPA) just as well as it mounts inside a hub.
66

7-
**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-devframe orchestration (docks, terminals, messages, commands). It does not ship UI - hub UI providers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. It does ship a **headless client runtime** (`createDevframeClientRuntime()` from `@devframes/hub/client`): booted in the host page, it assembles the shared `DevframeClientContext` (panel, docks, commands, when) and imports each dock entry's client script (`action` / `custom-render` / iframe `clientScript`) into that page - how a built-in devframe like the a11y inspector runs its page script inside the user app's page. See `examples/hub-vite/` for a working ~120-line Vite host demonstrating the protocol end to end.
7+
**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-devframe orchestration (docks, terminals, messages, commands). It does not ship UI - hub UI providers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. It does ship a **headless client runtime** (`createDevframeClientRuntime()` from `@devframes/hub/client`): booted in the host page, it assembles the shared `DevframeClientContext` (panel, docks, commands, when) and imports each dock entry's client script (`action` / `custom-render` / iframe `clientScript`) into that page - how a built-in devframe like the a11y inspector runs its page script inside the user app's page. See `examples/custom-hub-vite/` for a working ~120-line Vite host demonstrating the protocol end to end.
88

99
## Terminology
1010

@@ -73,7 +73,7 @@ The framework kits - `@devframes/vite`, `@devframes/nuxt`, `@devframes/next` - e
7373
- **`.../hub`** - **mount a whole `@devframes/hub` (many devframes) inside that tool** (the "I'm standing up devtools" scope). Wraps `initHub`, defaults the UI slot to `@devframes/hub-ui`'s `createUi()` (overridable via `ui`, or `ui: false` for headless), and ships a browser client helper at `.../hub/client` (a thin, lifecycle-managing wrapper over `@devframes/hub/client`'s `createDevframeClientRuntime`). `@devframes/hub` and `@devframes/hub-ui` are **optional peers** of these packages; `hub-ui` is loaded lazily (a bundler-ignored dynamic `import()` in the Next hub) so it stays optional and its `import.meta.url` asset lookups resolve at request time.
7474
- **The bare root (`.`) throws** a helpful error pointing at the two subpaths - never put real code on it.
7575
- **Vite and Nuxt already have native hub UI providers** (`@vitejs/devtools-kit`, `@nuxt/devtools`), so `@devframes/vite/hub` and `@devframes/nuxt/hub` still work but emit a one-time `console.warn` recommending those (silence with `{ quiet: true }`). `@devframes/next/hub` has no native counterpart, so it warns nothing.
76-
- The **full hub examples** (`examples/hub-vite`, `examples/hub-next`) consume `.../hub` on the node side but keep hand-rolling their own hub UI provider against `@devframes/hub/client` with `ui: false` - that hand-rolled hub UI provider is the whole point of those reference hosts. The **minimal** ones (`examples/hub-*-minimal`) consume `.../hub` with the default `@devframes/hub-ui` and inject its `embedded.js`, needing no browser-side code.
76+
- The **full hub examples** (`examples/custom-hub-vite`, `examples/custom-hub-next`) consume `.../hub` on the node side but keep hand-rolling their own hub UI provider against `@devframes/hub/client` with `ui: false` - that hand-rolled hub UI provider is the whole point of those reference hosts. The **minimal** ones (`examples/hub-vite`, `examples/hub-next`, `examples/hub-deno`, `examples/hub-fastify`, `examples/hub-hono`, `examples/hub-nitro`, `examples/hub-rsbuild`, `examples/hub-sveltekit`) consume `.../hub` with the default `@devframes/hub-ui` and inject its `embedded.js`, needing no browser-side code.
7777

7878
### Design system
7979

@@ -105,7 +105,7 @@ These reinforce devframe's positioning as "the container for one devtool integra
105105

106106
### Hub example parity
107107

108-
`examples/hub-vite/` (Vite plugin + vanilla client) and `examples/hub-next/` (Next.js App Router + React client) are the two reference hosts, and they stay at **feature parity**. They mount the same set of plugins and demo devframes, expose the same dock rail / iframe stage / subsystem drawer, and speak the same hub protocol - the only differences should be the host framework's own plumbing (how static assets are mounted, how the side-car server starts, how the client is rendered).
108+
`examples/custom-hub-vite/` (Vite plugin + vanilla client) and `examples/custom-hub-next/` (Next.js App Router + React client) are the two reference hosts, and they stay at **feature parity**. They mount the same set of plugins and demo devframes, expose the same dock rail / iframe stage / subsystem drawer, and speak the same hub protocol - the only differences should be the host framework's own plumbing (how static assets are mounted, how the side-car server starts, how the client is rendered).
109109

110110
Any change to one lands in the other in the same PR: adding a dock, wiring a new hub subsystem, changing the drawer layout, adopting a new client-runtime API. Their READMEs mirror each other too. If a capability genuinely can't exist on one host, say so explicitly in both READMEs rather than letting the examples silently drift.
111111

docs/app/components/global/DevframeEcosystemMap.vue

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ const nodes: EcosystemNode[] = [
185185
linksFrom: 'handler',
186186
label: 'Nitro',
187187
icon: 'i-unjs-nitro',
188-
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-nitro-minimal',
188+
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-nitro',
189189
color: 'neutral',
190190
shape: 'pill',
191191
style: 'dashed',
@@ -198,7 +198,7 @@ const nodes: EcosystemNode[] = [
198198
linksFrom: { source: 'handler', direction: 'vertical' },
199199
label: 'Hono',
200200
icon: 'i-logos-hono',
201-
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-hono-minimal',
201+
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-hono',
202202
color: 'neutral',
203203
shape: 'pill',
204204
style: 'dashed',
@@ -211,7 +211,7 @@ const nodes: EcosystemNode[] = [
211211
linksFrom: { source: 'handler', dashed: true, direction: 'vertical' },
212212
label: 'Next.js',
213213
icon: 'i-logos-nextjs-icon',
214-
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-next-minimal',
214+
href: 'https://github.com/devframes/devframe/tree/main/examples/hub-next',
215215
color: 'neutral',
216216
shape: 'pill',
217217
style: 'dashed',

docs/content/1.guide/16.hub.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: '@devframes/hub orchestrates many devtools sharing a UI: a dock reg
99

1010
![Hub screenshot](/screenshots/hub-1.png)
1111

12-
_Orchestrating multiple devtools (from [A Playground](https://github.com/devframes/devframe/tree/main/examples/hub-vite))_
12+
_Orchestrating multiple devtools (from [A Playground](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite))_
1313

1414
## What the hub adds
1515

@@ -248,8 +248,8 @@ The hub ships a headless client runtime, `createDevframeClientRuntime()` (`@devf
248248

249249
Two minimal hubs mount every built-in devframe behind an icon dock, plus a "Tabbed Tool" demonstrating [shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation):
250250

251-
- [`examples/hub-vite/`](https://github.com/devframes/devframe/tree/main/examples/hub-vite): a ~120-line Vite host with a vanilla DOM UI.
252-
- [`examples/hub-next/`](https://github.com/devframes/devframe/tree/main/examples/hub-next): the same, from a Next.js App Router app.
251+
- [`examples/custom-hub-vite/`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite): a ~120-line Vite host with a vanilla DOM UI.
252+
- [`examples/custom-hub-next/`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next): the same, from a Next.js App Router app.
253253

254254
## Diagnostics
255255

docs/content/1.guide/17.client-context.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,4 +108,4 @@ It materializes a [client-only dock](#client-only-docks) per tab (id `<frameId>:
108108

109109
### The hub UI provider's part
110110

111-
A hub UI provider keeps one iframe alive per `frameId` (shown/hidden); on mount, it sets the element on the anchor's `docks.getStateById(anchorId)` state (`domElements.iframe`) and emits `dom:iframe:mounted`. See the "Tabbed Tool" in [`examples/hub-vite`](https://github.com/devframes/devframe/tree/main/examples/hub-vite) / [`hub-next`](https://github.com/devframes/devframe/tree/main/examples/hub-next).
111+
A hub UI provider keeps one iframe alive per `frameId` (shown/hidden); on mount, it sets the element on the anchor's `docks.getStateById(anchorId)` state (`domElements.iframe`) and emits `dom:iframe:mounted`. See the "Tabbed Tool" in [`examples/custom-hub-vite`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) / [`custom-hub-next`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next).

docs/content/1.guide/21.build-your-own-json-render-frontend.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: '@devframes/json-render-ui is the reference frontend, not the proto
66
---
77

88
`@devframes/json-render-ui` is the reference frontend, not the protocol; any
9-
implementation of the renderer contract replaces it. The [Next hub witness](https://github.com/devframes/devframe/tree/main/examples/hub-next) ships a React one at
9+
implementation of the renderer contract replaces it. The [Next hub witness](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next) ships a React one at
1010
`src/client/json-render/`.
1111

1212
## The contract

docs/content/1.guide/22.build-your-own-hub-ui.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,6 @@ Renderer modules self-style (sometimes via a shadow root). Keep a live
8989
## Reference points
9090

9191
- `packages/hub-ui`: the full reference hub UI provider (Vue, `@antfu/design`).
92-
- [`examples/hub-vite`](https://github.com/devframes/devframe/tree/main/examples/hub-vite) and
93-
[`examples/hub-next`](https://github.com/devframes/devframe/tree/main/examples/hub-next): hand-rolled
92+
- [`examples/custom-hub-vite`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) and
93+
[`examples/custom-hub-next`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next): hand-rolled
9494
hub UI providers in vanilla DOM and React.

docs/content/1.guide/23.built-with.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,18 +41,18 @@ pnpm --filter <example-name> dev
4141
| [json-render](https://github.com/devframes/devframe/tree/main/examples/json-render) | Vue | Server-authored view via `@devframes/json-render-ui`; live state + action bridge. |
4242
| [streaming-chat](https://github.com/devframes/devframe/tree/main/examples/streaming-chat) | Preact | Streams tokens; history in shared state. |
4343
| [next-runtime-snapshot](https://github.com/devframes/devframe/tree/main/examples/next-runtime-snapshot) | React (Next.js) | App Router SPA surfacing the Node runtime. |
44-
| [hub-vite](https://github.com/devframes/devframe/tree/main/examples/hub-vite) | Vanilla TS (Vite) | ~120-line Vite host wiring `@devframes/hub`; hand-built hub UI provider. |
45-
| [hub-next](https://github.com/devframes/devframe/tree/main/examples/hub-next) | React (Next.js) | Same protocol, Next.js route. |
44+
| [custom-hub-vite](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) | Vanilla TS (Vite) | ~120-line Vite host wiring `@devframes/hub`; hand-built hub UI provider. |
45+
| [custom-hub-next](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next) | React (Next.js) | Same protocol, Next.js route. |
4646

4747
The **minimal** family mounts `initHub({ ui: createUi() })` with `@devframes/hub-ui`:
4848

4949
| Example | Host framework | Shows |
5050
|---------|------|-------|
51-
| [hub-vite-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-vite-minimal) | Vite | Dev middleware. |
52-
| [hub-next-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-next-minimal) | Next.js | App Router route. |
53-
| [hub-nitro-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-nitro-minimal) | Nitro | Catch-all route. |
54-
| [hub-hono-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-hono-minimal) | Hono | Node and Bun. |
55-
| [hub-fastify-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-fastify-minimal) | Fastify | `nodeMiddleware`. |
56-
| [hub-sveltekit-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-sveltekit-minimal) | SvelteKit | Catch-all endpoint. |
57-
| [hub-deno-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-deno-minimal) | Deno | `Deno.serve` + upgrade socket. |
58-
| [hub-rsbuild-minimal](https://github.com/devframes/devframe/tree/main/examples/hub-rsbuild-minimal) | Rsbuild | Dev middleware. |
51+
| [hub-vite](https://github.com/devframes/devframe/tree/main/examples/hub-vite) | Vite | Dev middleware. |
52+
| [hub-next](https://github.com/devframes/devframe/tree/main/examples/hub-next) | Next.js | App Router route. |
53+
| [hub-nitro](https://github.com/devframes/devframe/tree/main/examples/hub-nitro) | Nitro | Catch-all route. |
54+
| [hub-hono](https://github.com/devframes/devframe/tree/main/examples/hub-hono) | Hono | Node and Bun. |
55+
| [hub-fastify](https://github.com/devframes/devframe/tree/main/examples/hub-fastify) | Fastify | `nodeMiddleware`. |
56+
| [hub-sveltekit](https://github.com/devframes/devframe/tree/main/examples/hub-sveltekit) | SvelteKit | Catch-all endpoint. |
57+
| [hub-deno](https://github.com/devframes/devframe/tree/main/examples/hub-deno) | Deno | `Deno.serve` + upgrade socket. |
58+
| [hub-rsbuild](https://github.com/devframes/devframe/tree/main/examples/hub-rsbuild) | Rsbuild | Dev middleware. |

docs/content/1.guide/8.json-render.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ view renders full-bleed, multiple get a `title`-labeled switcher.
105105
A custom frontend renders from shared state: connect with `connectDevframe()`,
106106
read the view's state (keyed `devframe:json-render:<scope>:<id>`), subscribe to
107107
`updated` events, and render with your registry; the [Next
108-
hub example](https://github.com/devframes/devframe/tree/main/examples/hub-next) has a React renderer. In a
108+
hub example](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next) has a React renderer. In a
109109
**static** build spec + state are read-only: actions unavailable, local
110110
state and bindings still work.
111111

docs/content/3.frameworks/3.next.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ export const GET = handler.fetch
5353

5454
## Hosting a hub
5555

56-
[`@devframes/hub`](/guide/hub)'s `initHub` mounts every devframe under `<base><id>/` behind one `handler` (memoize on `globalThis`; see `examples/hub-next`):
56+
[`@devframes/hub`](/guide/hub)'s `initHub` mounts every devframe under `<base><id>/` behind one `handler` (memoize on `globalThis`; see `examples/custom-hub-next`):
5757

5858
```ts [devframe/host.ts]
5959
import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
@@ -133,4 +133,4 @@ No native hub UI provider here, so this scope stays quiet; `createDevframeNextHo
133133

134134
- [Vite](/frameworks/vite)
135135
- [Hub](/guide/hub)
136-
- [hub-next](https://github.com/devframes/devframe/tree/main/examples/hub-next)
136+
- [custom-hub-next](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next)

docs/content/6.errors/DF0076.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ hub.attach(myNodeHttpServer) // ✗ throws DF0076 on Bun/Deno
2323

2424
## Fix
2525

26-
On Bun/Deno, serve the advertised `__ws` route from `Bun.serve` / `Deno.serve` and complete the upgrade with `attachBunWsTransport` / `attachDenoWsTransport` (see the `hub-deno-minimal` example), or connect over the SSE endpoint instead; it rides the instance's ordinary HTTP surface and needs no upgrade wiring. A side-car (`ws: { sidecar: true }`) also binds the native WebSocket adapter for you on its own port.
26+
On Bun/Deno, serve the advertised `__ws` route from `Bun.serve` / `Deno.serve` and complete the upgrade with `attachBunWsTransport` / `attachDenoWsTransport` (see the `hub-deno` example), or connect over the SSE endpoint instead; it rides the instance's ordinary HTTP surface and needs no upgrade wiring. A side-car (`ws: { sidecar: true }`) also binds the native WebSocket adapter for you on its own port.
2727

2828
## Source
2929

0 commit comments

Comments
 (0)