Skip to content

Commit ec59a66

Browse files
antfubotantfubot
committed
docs: carve framework packages into a Frameworks section, regroup the Guide
The three `@devframes/*` framework packages no longer sit under "Helpers" (they're first-class packages, not `devframe/*` helpers) — they move into a new top-level **Frameworks** section (`docs/frameworks/`) with a cross- framework overview plus one page each for Vite / Nuxt / Next, organized around the two scopes (`/dev-spa` authoring one devframe, `/hub` mounting a hub). "Helpers" keeps just the genuine helpers (utilities + recipes). Also breaks the flat 21-item Guide sidebar into labelled subsections (Fundamentals / Client & Security / JSON-Render / Hub / Recipes & Advanced) — the top-nav dropdown still renders the flattened list. Renames the Adapters "Vite" entry to "Vite DevTools" to disambiguate the external `@vitejs/devtools-kit` adapter from `@devframes/vite`, and updates every cross-link to the moved pages. This PR was created with the help of an agent.
1 parent 41fd4b9 commit ec59a66

8 files changed

Lines changed: 116 additions & 41 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 70 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -16,30 +16,60 @@ function listErrorCodes(prefix: string): string[] {
1616
.sort()
1717
}
1818

19-
function guideItems(prefix: string) {
19+
function guideGroups(prefix: string) {
2020
return [
21-
{ text: 'Introduction', link: `${prefix}/guide/` },
22-
{ text: 'Devframe Definition', link: `${prefix}/guide/devframe-definition` },
23-
{ text: 'Scoped Context', link: `${prefix}/guide/scoped-context` },
24-
{ text: 'Cross-Plugin Services', link: `${prefix}/guide/services` },
25-
{ text: 'RPC', link: `${prefix}/guide/rpc` },
26-
{ text: 'Shared State', link: `${prefix}/guide/shared-state` },
27-
{ text: 'JSON-Render', link: `${prefix}/guide/json-render` },
28-
{ text: 'Streaming', link: `${prefix}/guide/streaming` },
29-
{ text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
30-
{ text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
31-
{ text: 'Client', link: `${prefix}/guide/client` },
32-
{ text: 'Transports', link: `${prefix}/guide/transports` },
33-
{ text: 'Security', link: `${prefix}/guide/security` },
34-
{ text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
35-
{ text: 'Hub', link: `${prefix}/guide/hub` },
36-
{ text: 'Serve a Hub Anywhere', link: `${prefix}/guide/hub-initiate` },
37-
{ text: 'Deep Linking', link: `${prefix}/guide/deep-linking` },
38-
{ text: 'Client Scripts & Context', link: `${prefix}/guide/client-context` },
39-
{ text: 'Build Your Own Hub UI', link: `${prefix}/guide/build-your-own-hub-ui` },
40-
{ text: 'Build Your Own JSON-Render Frontend', link: `${prefix}/guide/build-your-own-json-render-frontend` },
41-
{ text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },
42-
] satisfies DefaultTheme.NavItemWithLink[]
21+
{
22+
text: 'Fundamentals',
23+
items: [
24+
{ text: 'Introduction', link: `${prefix}/guide/` },
25+
{ text: 'Devframe Definition', link: `${prefix}/guide/devframe-definition` },
26+
{ text: 'Scoped Context', link: `${prefix}/guide/scoped-context` },
27+
{ text: 'Cross-Plugin Services', link: `${prefix}/guide/services` },
28+
{ text: 'RPC', link: `${prefix}/guide/rpc` },
29+
{ text: 'Shared State', link: `${prefix}/guide/shared-state` },
30+
{ text: 'Streaming', link: `${prefix}/guide/streaming` },
31+
{ text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
32+
{ text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
33+
],
34+
},
35+
{
36+
text: 'Client & Security',
37+
items: [
38+
{ text: 'Client', link: `${prefix}/guide/client` },
39+
{ text: 'Transports', link: `${prefix}/guide/transports` },
40+
{ text: 'Security', link: `${prefix}/guide/security` },
41+
{ text: 'Deep Linking', link: `${prefix}/guide/deep-linking` },
42+
],
43+
},
44+
{
45+
text: 'JSON-Render',
46+
items: [
47+
{ text: 'JSON-Render', link: `${prefix}/guide/json-render` },
48+
{ text: 'Build Your Own JSON-Render Frontend', link: `${prefix}/guide/build-your-own-json-render-frontend` },
49+
],
50+
},
51+
{
52+
text: 'Hub',
53+
items: [
54+
{ text: 'Hub', link: `${prefix}/guide/hub` },
55+
{ text: 'Serve a Hub Anywhere', link: `${prefix}/guide/hub-initiate` },
56+
{ text: 'Client Scripts & Context', link: `${prefix}/guide/client-context` },
57+
{ text: 'Build Your Own Hub UI', link: `${prefix}/guide/build-your-own-hub-ui` },
58+
],
59+
},
60+
{
61+
text: 'Recipes & Advanced',
62+
items: [
63+
{ text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
64+
{ text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },
65+
],
66+
},
67+
] satisfies { text: string, items: DefaultTheme.NavItemWithLink[] }[]
68+
}
69+
70+
/** Flattened guide list — used by the top nav dropdown, which renders one level. */
71+
function guideItems(prefix: string) {
72+
return guideGroups(prefix).flatMap(group => group.items) satisfies DefaultTheme.NavItemWithLink[]
4373
}
4474

4575
function adaptersItems(prefix: string) {
@@ -49,19 +79,25 @@ function adaptersItems(prefix: string) {
4979
{ text: 'Dev', link: `${prefix}/adapters/dev` },
5080
{ text: 'Initiate (middleware)', link: `${prefix}/adapters/initiate` },
5181
{ text: 'Build', link: `${prefix}/adapters/build` },
52-
{ text: 'Vite', link: `${prefix}/adapters/vite` },
82+
{ text: 'Vite DevTools', link: `${prefix}/adapters/vite` },
5383
{ text: 'Embedded', link: `${prefix}/adapters/embedded` },
5484
{ text: 'MCP', link: `${prefix}/adapters/mcp` },
5585
] satisfies DefaultTheme.NavItemWithLink[]
5686
}
5787

88+
function frameworksItems(prefix: string) {
89+
return [
90+
{ text: 'Overview', link: `${prefix}/frameworks/` },
91+
{ text: 'Vite', link: `${prefix}/frameworks/vite` },
92+
{ text: 'Nuxt', link: `${prefix}/frameworks/nuxt` },
93+
{ text: 'Next', link: `${prefix}/frameworks/next` },
94+
] satisfies DefaultTheme.NavItemWithLink[]
95+
}
96+
5897
function helpersItems(prefix: string) {
5998
return [
6099
{ text: 'Overview', link: `${prefix}/helpers/` },
61100
{ text: 'Utilities', link: `${prefix}/helpers/utilities` },
62-
{ text: 'Vite Plugin', link: `${prefix}/helpers/vite-bridge` },
63-
{ text: 'Nuxt Module', link: `${prefix}/helpers/nuxt` },
64-
{ text: 'Next Helper', link: `${prefix}/helpers/next` },
65101
{ text: 'Common RPC Functions', link: `${prefix}/helpers/common-rpc-functions` },
66102
{ text: 'Interactive Auth', link: `${prefix}/helpers/interactive-auth` },
67103
] satisfies DefaultTheme.NavItemWithLink[]
@@ -103,12 +139,17 @@ export function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[] {
103139
return [
104140
{
105141
text: 'Guide',
106-
items: guideItems(prefix),
142+
// Labelled, collapsible subsections instead of one long flat list.
143+
items: guideGroups(prefix).map(group => ({ ...group, collapsed: false })),
107144
},
108145
{
109146
text: 'Adapters',
110147
items: adaptersItems(prefix),
111148
},
149+
{
150+
text: 'Frameworks',
151+
items: frameworksItems(prefix),
152+
},
112153
{
113154
text: 'Helpers',
114155
items: helpersItems(prefix),
@@ -137,6 +178,7 @@ export function devframeNav(prefix = ''): DefaultTheme.NavItem[] {
137178
text: 'Adapters',
138179
items: [
139180
...adaptersItems(prefix),
181+
{ text: 'Frameworks', items: frameworksItems(prefix) },
140182
{ text: 'Helpers', items: helpersItems(prefix) },
141183
],
142184
},

‎docs/frameworks/index.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# Frameworks
6+
7+
The framework packages — [`@devframes/vite`](./vite), [`@devframes/nuxt`](./nuxt), and [`@devframes/next`](./next) — integrate devframe with a specific meta-framework's dev server. Each one splits into **two clearly-scoped subpaths**, because you're always doing one of two distinct jobs:
8+
9+
| Scope | Subpath | You are… |
10+
|-------|---------|----------|
11+
| **dev-spa** | `.../dev-spa` | building & dev-serving a **single devframe's SPA** with that tool |
12+
| **hub** | `.../hub` | mounting a whole **[devframes-hub](/guide/hub)** (many integrations) inside that tool |
13+
14+
The bare package root (`@devframes/vite`, `@devframes/nuxt`, `@devframes/next`) has no export — it throws with a pointer to the two subpaths, so an accidental bare import fails loudly instead of resolving to nothing.
15+
16+
| Package | dev-spa | hub |
17+
|---------|---------|-----|
18+
| [`@devframes/vite`](./vite) | `devframeVitePlugin` / `devframeViteBridge` / `devframeVite` | `viteDevframeHub` (+ `/hub/client`) |
19+
| [`@devframes/nuxt`](./nuxt) | the Nuxt module (`modules: ['@devframes/nuxt/dev-spa']`) | the hub Nuxt module (+ `/hub/client`) |
20+
| [`@devframes/next`](./next) | `withDevframe` + `createDevframeNextHandler` (+ `/dev-spa/client`) | `nextDevframeHub` (+ `/hub/client`) |
21+
22+
## dev-spa: author one devframe
23+
24+
The `dev-spa` scope is for when the thing you're building **is** a devframe — you author its UI with Vite/Nuxt/Next and want its RPC backend running during development. See each package's page for the details; for the framework-neutral CLI/build/embedded outputs, reach for the [adapters](/adapters/) instead.
25+
26+
## hub: mount a devframes-hub
27+
28+
The `hub` scope mounts an [`@devframes/hub`](/guide/hub) — many integrations under one namespace, one merged RPC registry — inside the tool's dev server. Each `hub` entry wraps [`initHub`](/guide/hub-initiate), defaults the UI slot to [`@devframes/hub-ui`](/guide/build-your-own-hub-ui)'s `createUi()` (override with `ui`, or `ui: false` for a headless hub you drive with the matching `/hub/client` helper), and mounts everything behind one catch-all.
29+
30+
- **[Vite](./vite#mounting-a-hub)** — `viteDevframeHub()` shares Vite's dev server and injects the floating dock.
31+
- **[Nuxt](./nuxt#mounting-a-hub)** — the hub Nuxt module wires the Vite hub plugin into `nuxt dev`.
32+
- **[Next](./next#mounting-a-hub)** — `nextDevframeHub()` serves the hub from one App Router route on a side-car socket.
33+
34+
Vite and Nuxt already have native hub viewers ([Vite DevTools](https://devtools.vite.dev), [Nuxt DevTools](https://devtools.nuxt.com)) that integrate the same hub protocol, so `@devframes/vite/hub` and `@devframes/nuxt/hub` print a one-time recommendation to prefer those (silence with `{ quiet: true }`). Next has no native counterpart, so `@devframes/next/hub` stays quiet.

docs/helpers/next.md renamed to docs/frameworks/next.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
outline: deep
33
---
44

5-
# Next Helper
5+
# Next
66

77
> [!WARNING]
88
> Experimental. `@devframes/next`'s API is still settling — expect changes before a stable release.
99
10-
`@devframes/next` hosts devframes from a Next.js App Router app. Next runs on webpack/Turbopack rather than Vite, so it hosts through a route handler instead of the [Vite Bridge](./vite-bridge): the package serves each devframe's SPA and its `__connection.json` from a single `fetch` handler your catch-all route delegates to, reusing devframe's own [`serveStaticHandler`](/adapters/dev) for SPA fallback, content types, and path-traversal guarding.
10+
`@devframes/next` hosts devframes from a Next.js App Router app. Next runs on webpack/Turbopack rather than Vite, so it hosts through a route handler instead of the [Vite](./vite): the package serves each devframe's SPA and its `__connection.json` from a single `fetch` handler your catch-all route delegates to, reusing devframe's own [`serveStaticHandler`](/adapters/dev) for SPA fallback, content types, and path-traversal guarding.
1111

1212
`@devframes/next` splits into two scopes: `@devframes/next/dev-spa` (author one devframe with Next) and [`@devframes/next/hub`](#mounting-a-hub) (mount a whole devframes-hub). The bare `@devframes/next` import throws with a pointer to both.
1313

@@ -140,6 +140,6 @@ Unlike Vite and Nuxt, Next has no native hub viewer, so this scope prints no rec
140140

141141
## See also
142142

143-
- [Vite Bridge](./vite-bridge) — the equivalent for Vite-based hosts
143+
- [Vite](./vite) — the equivalent for Vite-based hosts
144144
- [Hub](/guide/hub) — `initHub`, `ctx.install`, and `DevframeHost`
145145
- [hub-next](/examples/hub-next) — a full working host

docs/helpers/nuxt.md renamed to docs/frameworks/nuxt.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
outline: deep
33
---
44

5-
# Nuxt Helper
5+
# Nuxt
66

77
The `@devframes/nuxt/dev-spa` module wires a Nuxt-built SPA as a devframe client, and optionally serves the dev-time RPC bridge alongside `nuxt dev`. It runs inside the Nuxt app that consumes your devframe.
88

docs/helpers/vite-bridge.md renamed to docs/frameworks/vite.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
outline: deep
33
---
44

5-
# @devframes/vite
5+
# Vite
66

77
`@devframes/vite` splits into two scopes: **`@devframes/vite/dev-spa`** (this page — dev-serve one devframe's SPA with Vite) and [**`@devframes/vite/hub`**](#mounting-a-hub) (mount a whole devframes-hub inside a Vite app). The bare `@devframes/vite` import throws with a pointer to both.
88

‎docs/guide/migration-0.9.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ export default defineConfig({
279279
})
280280
```
281281

282-
`@devframes/vite` (and `@devframes/nuxt` / `@devframes/next`) take `@devframes/hub` and `@devframes/hub-ui` as **optional** peers — only the `/hub` scope needs them. Install `vite` as a peer as before. See [`@devframes/vite`](/helpers/vite-bridge) for the full reference.
282+
`@devframes/vite` (and `@devframes/nuxt` / `@devframes/next`) take `@devframes/hub` and `@devframes/hub-ui` as **optional** peers — only the `/hub` scope needs them. Install `vite` as a peer as before. See [`@devframes/vite`](/frameworks/vite) for the full reference.
283283

284284
## `@devframes/nuxt` and `@devframes/next` split into `/dev-spa` and `/hub`
285285

@@ -325,4 +325,4 @@ export const POST = (req: Request) => hub.handler(req)
325325
export const DELETE = (req: Request) => hub.handler(req)
326326
```
327327

328-
Vite and Nuxt already have native hub viewers, so `@devframes/vite/hub` and `@devframes/nuxt/hub` print a one-time recommendation to prefer [Vite DevTools](https://devtools.vite.dev) / [Nuxt DevTools](https://devtools.nuxt.com) (silence with `{ quiet: true }`); `@devframes/next/hub` has no native counterpart and stays quiet. See [`@devframes/vite`](/helpers/vite-bridge#mounting-a-hub), [`@devframes/nuxt`](/helpers/nuxt#mounting-a-hub), and [`@devframes/next`](/helpers/next#mounting-a-hub).
328+
Vite and Nuxt already have native hub viewers, so `@devframes/vite/hub` and `@devframes/nuxt/hub` print a one-time recommendation to prefer [Vite DevTools](https://devtools.vite.dev) / [Nuxt DevTools](https://devtools.nuxt.com) (silence with `{ quiet: true }`); `@devframes/next/hub` has no native counterpart and stays quiet. See [`@devframes/vite`](/frameworks/vite#mounting-a-hub), [`@devframes/nuxt`](/frameworks/nuxt#mounting-a-hub), and [`@devframes/next`](/frameworks/next#mounting-a-hub).

‎docs/guide/standalone-cli.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ export default defineNuxtConfig({
9898
})
9999
```
100100

101-
Build with `nuxt build` and point `cli.distDir` at `./dist/public`. The SPA discovers its effective base at runtime — no `--base` rewrite needed. See the [Nuxt helper docs](/helpers/nuxt) for the full reference.
101+
Build with `nuxt build` and point `cli.distDir` at `./dist/public`. The SPA discovers its effective base at runtime — no `--base` rewrite needed. See the [Nuxt docs](/frameworks/nuxt) for the full reference.
102102

103103
## Next.js SPA setup
104104

‎docs/helpers/index.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,14 @@ outline: deep
44

55
# Helpers
66

7-
Helpers are the optional, opt-in surface around the core `defineDevframe` API: small wrappers for runtime integration, prebuilt RPC recipes, and a curated set of low-level utilities. None of them are required to ship a devframe — reach for them when they match the shape of what you're building.
7+
Helpers are the optional, opt-in surface around the core `defineDevframe` API: prebuilt RPC recipes and a curated set of low-level utilities, all served from the `devframe` package itself. None of them are required to ship a devframe — reach for them when they match the shape of what you're building.
88

99
| Helper | Entry | What it does |
1010
|--------|-------|--------------|
1111
| [Utilities](./utilities) | `devframe/utils/*` | Bundled small utilities — terminal colors, hashing, editor launch, structured-clone serialization, and more. |
12-
| [Vite Plugin](./vite-bridge) | `@devframes/vite` | Vite plugins for mounting a devframe inside any Vite-based host (Astro, SolidStart, plain Vite) — a static mount, an RPC bridge, or a convenience wrapper over both. |
13-
| [Nuxt Module](./nuxt) | `@devframes/nuxt` | Nuxt module that wires a Nuxt SPA as a devframe client and serves the dev-time RPC bridge. |
14-
| [Next Helper](./next) | `@devframes/next` | Route-handler host + React client for mounting devframes inside a Next.js App Router app (experimental). |
1512
| [Common RPC Functions](./common-rpc-functions) | `devframe/recipes/common-rpc-functions` | Prebuilt RPC actions for "open in editor" and "reveal in Finder". |
1613
| [Interactive Auth](./interactive-auth) | `devframe/recipes/interactive-auth` | Ready-made OTP auth layer — handshake, resolver gate, connect-time trust, and the code/link banner. |
1714

18-
Helpers vs. [adapters](/adapters/): an adapter takes a `DevframeDefinition` and deploys it as a runnable surface (CLI, dev server, static build, MCP server). A helper is a smaller piece — a Vite plugin, a Nuxt module, a recipe, a utility function — that you compose alongside an adapter.
15+
Helpers vs. [adapters](/adapters/): an adapter takes a `DevframeDefinition` and deploys it as a runnable surface (CLI, dev server, static build, MCP server). A helper is a smaller piece — a recipe or a utility function — that you compose alongside an adapter.
16+
17+
For integrating a devframe (or a whole hub) with a specific meta-framework's dev server, see the dedicated [`@devframes/*` framework packages](/frameworks/) instead.

0 commit comments

Comments
 (0)