Skip to content

Commit 98a3c40

Browse files
os-zhuangclaude
andcommitted
docs(content): align user docs site with the 11 breaking changes
Sweep of content/docs/** (the docs.objectstack.ai site) for symbols/packages removed in 11. ADRs/audits and metric names (http_requests_total) left as-is; service-ai references kept (correctly documented as cloud/Enterprise). - packages.mdx + concepts/packages.mdx: Framework Adapters → Hono-only; removed the 6 non-Hono adapter sections, the plugin-msw sections, and fixed the dependency ASCII tree. - deployment-vercel.mdx: removed the broken Next.js "Option A" (@objectstack/nextjs); Hono is the server path; intro reframed + a callout flags the removed MSW mode. - environment-variables.mdx: alias table reframed (ecosystem names permanent/silent; OS_MULTI_TENANT / OBJECTSTACK_METADATA_WRITABLE / AUTH_BASE_URL removed-in-11 note). - one-liners: flow.mdx / business-logic.mdx (http_request→http), client-sdk.mdx (query aliases removed), metadata-service.mdx (IUIService removed), references/index.mdx (PolicySchema row), plugins.mdx (plugin-msw), schema.mdx / security.mdx / adding-a-metadata-type.mdx (env renames), authentication.mdx (removed the MSWPlugin browser-kernel example). Deferred (follow-up): deployment-vercel.mdx MSW-mode how-to section + its checklist/comparison entries, and implementation-status.mdx QA table column. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent f962f4f commit 98a3c40

14 files changed

Lines changed: 24 additions & 279 deletions

File tree

content/docs/concepts/packages.mdx

Lines changed: 2 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -335,37 +335,7 @@ The package does **not** export schemas from the root; import the domain you nee
335335

336336
## Framework Adapters
337337

338-
Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specific HTTP frameworks.
339-
340-
### @objectstack/express
341-
342-
**Description:** Express Framework Adapter
343-
344-
**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Express routes.
345-
346-
**Key Features:**
347-
- Maps standard routes to Express handlers
348-
- Supports Express v5 middleware chain
349-
- Bearer token authentication via AuthPlugin
350-
351-
**Implementation Status:****FULLY IMPLEMENTED**
352-
353-
---
354-
355-
### @objectstack/fastify
356-
357-
**Description:** Fastify Framework Adapter
358-
359-
**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Fastify routes.
360-
361-
**Key Features:**
362-
- Maps standard routes to Fastify handlers
363-
- Supports Fastify v5 plugin system
364-
- Bearer token authentication via AuthPlugin
365-
366-
**Implementation Status:****FULLY IMPLEMENTED**
367-
368-
---
338+
The open edition ships the **Hono** adapter. For another framework, build a thin adapter on the public `HttpDispatcher` API — the previous Express / Fastify / Next.js / NestJS / Nuxt / SvelteKit adapters were removed in 11 and can be vendored out-of-tree.
369339

370340
### @objectstack/hono
371341

@@ -382,66 +352,6 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi
382352

383353
---
384354

385-
### @objectstack/nestjs
386-
387-
**Description:** NestJS Framework Adapter
388-
389-
**Purpose:** Integrates ObjectStack as a NestJS module with automatic controller generation.
390-
391-
**Key Features:**
392-
- NestJS module registration
393-
- Automatic controller generation from metadata
394-
- Dependency injection integration
395-
396-
**Implementation Status:** 🔄 **IN PROGRESS**
397-
398-
---
399-
400-
### @objectstack/nextjs
401-
402-
**Description:** Next.js Framework Adapter
403-
404-
**Purpose:** Integrates ObjectStack with Next.js App Router and API routes.
405-
406-
**Key Features:**
407-
- App Router integration
408-
- API route handlers
409-
- Server-side data access and server actions
410-
411-
**Implementation Status:****FULLY IMPLEMENTED**
412-
413-
---
414-
415-
### @objectstack/nuxt
416-
417-
**Description:** Nuxt Framework Adapter
418-
419-
**Purpose:** Integrates ObjectStack with Nuxt server routes via h3.
420-
421-
**Key Features:**
422-
- h3 event handler integration
423-
- Nitro server route support
424-
- Bearer token authentication via AuthPlugin
425-
426-
**Implementation Status:****FULLY IMPLEMENTED**
427-
428-
---
429-
430-
### @objectstack/sveltekit
431-
432-
**Description:** SvelteKit Framework Adapter
433-
434-
**Purpose:** Integrates ObjectStack with SvelteKit hooks and server routes.
435-
436-
**Key Features:**
437-
- SvelteKit handle hook integration
438-
- Server route handlers
439-
- Bearer token authentication via AuthPlugin
440-
441-
**Implementation Status:****FULLY IMPLEMENTED**
442-
443-
---
444-
445355
## Plugin Packages
446356

447357
### @objectstack/driver-memory
@@ -501,30 +411,6 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi
501411

502412
---
503413

504-
### @objectstack/plugin-msw
505-
506-
**Description:** Mock Service Worker (MSW) Plugin for ObjectStack Testing
507-
508-
**Purpose:** Testing plugin that mocks the entire ObjectStack backend in browser/node using the unified Runtime logic.
509-
510-
**Key Features:**
511-
- **Unified Dispatcher**: Uses `@objectstack/runtime`'s `HttpDispatcher` to behave exactly like the real server
512-
- **Full Protocol Mocking**: Mocks Auth, Metadata, Data, Storage, Analytics, and Automation endpoints
513-
- **Browser Testing**: High-fidelity backend simulation in browser environments
514-
- **Custom Handlers**: Support for custom request handlers
515-
- **Request Logging**: Built-in request/response logging
516-
- **Service Worker Based**: Uses MSW's service worker approach
517-
518-
**Use Cases:**
519-
- Unit testing React components
520-
- Integration testing frontend applications
521-
- Browser-based testing without backend
522-
- E2E testing with mocked APIs
523-
524-
**Implementation Status:****FULLY IMPLEMENTED** - Production ready for testing
525-
526-
---
527-
528414
### @objectstack/plugin-auth
529415

530416
**Description:** Authentication & Identity Plugin for ObjectStack
@@ -928,20 +814,12 @@ Trigger packages auto-launch flows in response to events (ADR-0018, ADR-0041).
928814
│ ├─→ @objectstack/client (consumes runtime APIs)
929815
│ │ ↓
930816
│ │ └─→ @objectstack/client-react (wraps client)
931-
│ └─→ Adapters:
932-
│ ├─→ @objectstack/express (Express routes)
933-
│ ├─→ @objectstack/fastify (Fastify routes)
934-
│ ├─→ @objectstack/hono (Hono routes)
935-
│ ├─→ @objectstack/nestjs (NestJS modules)
936-
│ ├─→ @objectstack/nextjs (Next.js routes)
937-
│ ├─→ @objectstack/nuxt (Nuxt/h3 routes)
938-
│ └─→ @objectstack/sveltekit (SvelteKit hooks)
817+
│ └─→ @objectstack/hono (Hono adapter)
939818
└─→ @objectstack/cli (validates against spec schemas)
940819
941820
Plugins (depend on core packages):
942821
├─→ @objectstack/driver-memory (implements driver interface)
943822
├─→ @objectstack/plugin-hono-server (HTTP server via @objectstack/hono)
944-
├─→ @objectstack/plugin-msw (mocks for testing via runtime)
945823
├─→ @objectstack/plugin-auth (authentication via better-auth)
946824
├─→ @objectstack/plugin-security (RBAC, RLS, field masking)
947825
└─→ @objectstack/plugin-dev (dev mode, all services in-memory)

content/docs/guides/adding-a-metadata-type.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ The single source of truth for built-in types is the
5858
5959
The `allowOrgOverride` flag is the **only** place that controls whether the
6060
overlay store accepts writes for this type. The runtime env-var
61-
`OS_METADATA_WRITABLE=foo,bar` (legacy alias: `OBJECTSTACK_METADATA_WRITABLE`)
61+
`OS_METADATA_WRITABLE=foo,bar`
6262
flips the flag on at runtime for the listed types — useful for opt-in writable
6363
behaviour in production. The allow-list is parsed and cached lazily on first
6464
use, not pinned at process start.

content/docs/guides/authentication.mdx

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -689,25 +689,6 @@ This ensures that registration and sign-in flows do not return 404 errors in MSW
689689

690690
> **Note:** In server mode with AuthPlugin loaded, the auth service handler takes priority and the mock fallback is never reached. The mock fallback only activates when AuthPlugin is not loaded (e.g. browser-only Console/MSW builds where `better-auth` is unavailable).
691691
692-
### Browser Kernel Factory
693-
694-
Browser-only Console builds cannot bundle the Node-only `better-auth` library.
695-
Instead of loading `AuthPlugin` directly, MSW mode can rely on
696-
`HttpDispatcher`'s built-in mock fallback to handle auth endpoints:
697-
698-
```typescript
699-
// browser test/mock kernel
700-
// No AuthPlugin needed — HttpDispatcher provides mock auth endpoints automatically
701-
const kernel = new ObjectKernel();
702-
await kernel.use(new ObjectQLPlugin());
703-
await kernel.use(new DriverPlugin(driver, 'memory'));
704-
// ...
705-
await kernel.use(new MSWPlugin({ /* ... */ }));
706-
await kernel.bootstrap();
707-
```
708-
709-
---
710-
711692
## Next Steps
712693

713694
- See [Security Guide](/docs/guides/security) for authorization and permissions

content/docs/guides/business-logic.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ export const contractExpirationCheck: Flow = {
219219
| `script` | Run an inline expression / function |
220220
| `loop`, `map` | Iterate over a collection |
221221
| `create_record`, `update_record`, `delete_record`, `get_record` | CRUD |
222-
| `http` | Outbound HTTP call (`http_request` is a deprecated alias) |
222+
| `http` | Outbound HTTP call |
223223
| `connector_action` | Invoke a registered connector action |
224224
| `notify` | In-app/email-style notification dispatch |
225225
| `wait`, `screen`, `approval` | Durable pauses |

content/docs/guides/client-sdk.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ The `find` method accepts an options object with **canonical** (recommended) fie
382382
| `expand` | `Record<string, any>` or `string[]` | Relation loading (JOIN) | `{ owner: {} }` |
383383

384384
<Callout type="warn">
385-
**Deprecated aliases:** The following legacy field names are still accepted for backward compatibility but will be removed in a future major version: `select``fields`, `filter`/`filters``where`, `sort``orderBy`, `top``limit`, `skip``offset`.
385+
**Removed in 11:** the legacy query-field aliases were removed — use the canonical names: `fields` (was `select`), `where` (was `filter`/`filters`), `orderBy` (was `sort`), `limit` (was `top`), `offset` (was `skip`).
386386
</Callout>
387387

388388
### Batch Options

content/docs/guides/contracts/metadata-service.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ console.log(result.failed); // failed
261261

262262
## UI Metadata (Views & Dashboards)
263263

264-
UI metadata types (`view`, `dashboard`, `page`, `app`, `theme`) are first-class citizens in the Metadata Service. The previously separate `IUIService` has been deprecated.
264+
UI metadata types (`view`, `dashboard`, `page`, `app`, `theme`) are first-class citizens in the Metadata Service. The previously separate `IUIService` was removed in 11 — use the Metadata Service for views/dashboards.
265265

266266
### Reading UI Metadata
267267

content/docs/guides/deployment-vercel.mdx

Lines changed: 6 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@ description: Deploy ObjectStack applications to Vercel — Server mode (recommen
55

66
# Deploy to Vercel
77

8-
ObjectStack supports two deployment modes on Vercel. **Server mode is recommended** for production. The published ObjectStack Studio/console ships as a static Vite SPA that points at a separate ObjectStack server (via `VITE_SERVER_URL`) — see the note under Option B.
8+
ObjectStack 11 deploys to Vercel in **server mode** — serverless functions running the **Hono** adapter (`@objectstack/hono`). The published ObjectStack Studio/console ships as a static Vite SPA that points at a separate ObjectStack server (via `VITE_SERVER_URL`).
9+
10+
<Callout type="warn">
11+
**Updated for 11.** The in-browser **MSW Mode** (`@objectstack/plugin-msw`) and the **Next.js adapter** (`@objectstack/nextjs`) were **removed in 11** and are no longer published. Use the Hono server path below. The "MSW Mode" how-to further down is retained for reference only and is slated for removal.
12+
</Callout>
913

1014
| Mode | Runtime | Vercel Feature | Use Case |
1115
| :--- | :--- | :--- | :--- |
1216
| **Server** (default) | Node.js / Edge | Serverless Functions | Production apps, Studio, real database |
13-
| **MSW** | Browser (Service Worker) | Static Site | Offline-only demos, prototypes |
1417

1518
---
1619

@@ -206,65 +209,7 @@ In Server mode, ObjectStack runs inside Vercel Serverless Functions. API request
206209
└───────────────────────────────────────────────────────────────┘
207210
```
208211

209-
### Option A: Next.js + `@objectstack/nextjs`
210-
211-
This is the recommended approach for Vercel. The `@objectstack/nextjs` adapter maps all ObjectStack protocol endpoints to a single Next.js catch-all route.
212-
213-
**1. Create the kernel singleton:**
214-
215-
```typescript
216-
// lib/kernel.ts
217-
import { ObjectKernel, DriverPlugin, AppPlugin } from '@objectstack/runtime';
218-
import { ObjectQLPlugin } from '@objectstack/objectql';
219-
import appConfig from '../objectstack.config';
220-
221-
let kernel: ObjectKernel | null = null;
222-
223-
export async function getKernel() {
224-
if (kernel) return kernel;
225-
226-
kernel = new ObjectKernel();
227-
await kernel.use(new ObjectQLPlugin());
228-
229-
// Use your production driver (Postgres, MongoDB, etc.)
230-
// await kernel.use(new DriverPlugin(new PostgresDriver({
231-
// url: process.env.DATABASE_URL,
232-
// })));
233-
234-
// Load the application configuration (objects, data, etc.)
235-
await kernel.use(new AppPlugin(appConfig));
236-
237-
await kernel.bootstrap();
238-
return kernel;
239-
}
240-
```
241-
242-
**2. Create the API route handler:**
243-
244-
```typescript
245-
// app/api/[...objectstack]/route.ts
246-
import { createRouteHandler } from '@objectstack/nextjs';
247-
import { getKernel } from '@/lib/kernel';
248-
249-
async function handler(...args: any[]) {
250-
const kernel = await getKernel();
251-
const routeHandler = createRouteHandler({ kernel, prefix: '/api' });
252-
return routeHandler(...args);
253-
}
254-
255-
export { handler as GET, handler as POST, handler as PATCH, handler as DELETE };
256-
```
257-
258-
**3. `vercel.json` (optional — Next.js works out of the box):**
259-
260-
```json
261-
{
262-
"$schema": "https://openapi.vercel.sh/vercel.json",
263-
"framework": "nextjs"
264-
}
265-
```
266-
267-
### Option B: Hono + `@objectstack/hono` (Vite SPA)
212+
### Hono serverless function (`@objectstack/hono`)
268213

269214
This is a valid self-contained pattern when you want to ship a Vite SPA *and* its API from a single Vercel project: the SPA is served as static assets, and a Hono-based serverless function handles `/api/*` requests.
270215

content/docs/guides/environment-variables.mdx

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -275,14 +275,15 @@ the hosted ObjectStack Cloud control plane.
275275

276276
## Legacy aliases
277277

278-
The names below still work this release but emit a one-shot deprecation
279-
warning. They will be removed in a future major.
278+
Some env vars accept a legacy alias for compatibility. **Ecosystem-standard names** (e.g. `DATABASE_URL`, `AUTH_SECRET`, `BETTER_AUTH_*`, `PORT`, `CORS_*`, `MCP_SERVER_*`) are permanently accepted and no longer warn. ObjectStack's own former names are deprecated — prefer the canonical `OS_*`.
279+
280+
> **Removed in 11** (rename required): `OS_MULTI_TENANT``OS_MULTI_ORG_ENABLED`, `OBJECTSTACK_METADATA_WRITABLE``OS_METADATA_WRITABLE`, `AUTH_BASE_URL`/`OS_AUTH_BASE_URL``OS_AUTH_URL`.
280281
281282
| Canonical | Legacy |
282283
|:---|:---|
283284
| `OS_PORT` | `PORT` |
284285
| `OS_DATABASE_URL` | `DATABASE_URL` |
285-
| `OS_AUTH_URL` | `BETTER_AUTH_URL`, `AUTH_BASE_URL`, `OS_AUTH_BASE_URL` |
286+
| `OS_AUTH_URL` | `BETTER_AUTH_URL` |
286287
| `OS_AUTH_SECRET` | `BETTER_AUTH_SECRET`, `AUTH_SECRET` |
287288
| `OS_ROOT_DOMAIN` | `ROOT_DOMAIN` |
288289
| `OS_CORS_ENABLED` | `CORS_ENABLED` |
@@ -293,8 +294,6 @@ warning. They will be removed in a future major.
293294
| `OS_MCP_SERVER_ENABLED` | `MCP_SERVER_ENABLED` |
294295
| `OS_MCP_SERVER_NAME` | `MCP_SERVER_NAME` |
295296
| `OS_MCP_SERVER_TRANSPORT` | `MCP_SERVER_TRANSPORT` |
296-
| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` |
297297
| `OS_NODE_ID` | `OBJECTSTACK_NODE_ID` |
298-
| `OS_METADATA_WRITABLE` | `OBJECTSTACK_METADATA_WRITABLE` |
299298
| `OS_HOME` | `OBJECTSTACK_HOME` |
300299
| `OS_DEV_CRYPTO_KEY` | `OBJECTSTACK_DEV_CRYPTO_KEY` |

content/docs/guides/metadata/flow.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ Each node performs a specific action in the flow.
108108
| `update_record` | Update existing records |
109109
| `delete_record` | Delete records |
110110
| `get_record` | Query records |
111-
| `http` | Make an HTTP API call (the deprecated alias `http_request` still resolves to this) |
111+
| `http` | Make an HTTP API call |
112112
| `script` | Run a custom script action (dispatched by `config.actionType`) |
113113
| `screen` | Display a user form/screen (durable pause) |
114114
| `wait` | Pause for a timer or named signal (durable pause; timers auto-resume) |
@@ -317,7 +317,7 @@ events).
317317
type: 'try_catch',
318318
label: 'Charge with fallback',
319319
config: {
320-
try: { nodes: [{ id: 'charge', type: 'http_request', label: 'Charge', config: { /**/ } }], edges: [] },
320+
try: { nodes: [{ id: 'charge', type: 'http', label: 'Charge', config: { /**/ } }], edges: [] },
321321
catch: { nodes: [{ id: 'flag', type: 'update_record', label: 'Flag failure', config: { /**/ } }], edges: [] },
322322
errorVariable: '$error',
323323
retry: { maxRetries: 3, retryDelayMs: 1000, backoffMultiplier: 2 },

0 commit comments

Comments
 (0)