Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 2 additions & 124 deletions content/docs/concepts/packages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -335,37 +335,7 @@ The package does **not** export schemas from the root; import the domain you nee

## Framework Adapters

Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specific HTTP frameworks.

### @objectstack/express

**Description:** Express Framework Adapter

**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Express routes.

**Key Features:**
- Maps standard routes to Express handlers
- Supports Express v5 middleware chain
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/fastify

**Description:** Fastify Framework Adapter

**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Fastify routes.

**Key Features:**
- Maps standard routes to Fastify handlers
- Supports Fastify v5 plugin system
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---
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.

### @objectstack/hono

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

---

### @objectstack/nestjs

**Description:** NestJS Framework Adapter

**Purpose:** Integrates ObjectStack as a NestJS module with automatic controller generation.

**Key Features:**
- NestJS module registration
- Automatic controller generation from metadata
- Dependency injection integration

**Implementation Status:** 🔄 **IN PROGRESS**

---

### @objectstack/nextjs

**Description:** Next.js Framework Adapter

**Purpose:** Integrates ObjectStack with Next.js App Router and API routes.

**Key Features:**
- App Router integration
- API route handlers
- Server-side data access and server actions

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/nuxt

**Description:** Nuxt Framework Adapter

**Purpose:** Integrates ObjectStack with Nuxt server routes via h3.

**Key Features:**
- h3 event handler integration
- Nitro server route support
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/sveltekit

**Description:** SvelteKit Framework Adapter

**Purpose:** Integrates ObjectStack with SvelteKit hooks and server routes.

**Key Features:**
- SvelteKit handle hook integration
- Server route handlers
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

## Plugin Packages

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

---

### @objectstack/plugin-msw

**Description:** Mock Service Worker (MSW) Plugin for ObjectStack Testing

**Purpose:** Testing plugin that mocks the entire ObjectStack backend in browser/node using the unified Runtime logic.

**Key Features:**
- **Unified Dispatcher**: Uses `@objectstack/runtime`'s `HttpDispatcher` to behave exactly like the real server
- **Full Protocol Mocking**: Mocks Auth, Metadata, Data, Storage, Analytics, and Automation endpoints
- **Browser Testing**: High-fidelity backend simulation in browser environments
- **Custom Handlers**: Support for custom request handlers
- **Request Logging**: Built-in request/response logging
- **Service Worker Based**: Uses MSW's service worker approach

**Use Cases:**
- Unit testing React components
- Integration testing frontend applications
- Browser-based testing without backend
- E2E testing with mocked APIs

**Implementation Status:** ✅ **FULLY IMPLEMENTED** - Production ready for testing

---

### @objectstack/plugin-auth

**Description:** Authentication & Identity Plugin for ObjectStack
Expand Down Expand Up @@ -928,20 +814,12 @@ Trigger packages auto-launch flows in response to events (ADR-0018, ADR-0041).
│ ├─→ @objectstack/client (consumes runtime APIs)
│ │ ↓
│ │ └─→ @objectstack/client-react (wraps client)
│ └─→ Adapters:
│ ├─→ @objectstack/express (Express routes)
│ ├─→ @objectstack/fastify (Fastify routes)
│ ├─→ @objectstack/hono (Hono routes)
│ ├─→ @objectstack/nestjs (NestJS modules)
│ ├─→ @objectstack/nextjs (Next.js routes)
│ ├─→ @objectstack/nuxt (Nuxt/h3 routes)
│ └─→ @objectstack/sveltekit (SvelteKit hooks)
│ └─→ @objectstack/hono (Hono adapter)
└─→ @objectstack/cli (validates against spec schemas)

Plugins (depend on core packages):
├─→ @objectstack/driver-memory (implements driver interface)
├─→ @objectstack/plugin-hono-server (HTTP server via @objectstack/hono)
├─→ @objectstack/plugin-msw (mocks for testing via runtime)
├─→ @objectstack/plugin-auth (authentication via better-auth)
├─→ @objectstack/plugin-security (RBAC, RLS, field masking)
└─→ @objectstack/plugin-dev (dev mode, all services in-memory)
Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/adding-a-metadata-type.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The single source of truth for built-in types is the

The `allowOrgOverride` flag is the **only** place that controls whether the
overlay store accepts writes for this type. The runtime env-var
`OS_METADATA_WRITABLE=foo,bar` (legacy alias: `OBJECTSTACK_METADATA_WRITABLE`)
`OS_METADATA_WRITABLE=foo,bar`
flips the flag on at runtime for the listed types — useful for opt-in writable
behaviour in production. The allow-list is parsed and cached lazily on first
use, not pinned at process start.
Expand Down
19 changes: 0 additions & 19 deletions content/docs/guides/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -689,25 +689,6 @@ This ensures that registration and sign-in flows do not return 404 errors in MSW

> **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).

### Browser Kernel Factory

Browser-only Console builds cannot bundle the Node-only `better-auth` library.
Instead of loading `AuthPlugin` directly, MSW mode can rely on
`HttpDispatcher`'s built-in mock fallback to handle auth endpoints:

```typescript
// browser test/mock kernel
// No AuthPlugin needed — HttpDispatcher provides mock auth endpoints automatically
const kernel = new ObjectKernel();
await kernel.use(new ObjectQLPlugin());
await kernel.use(new DriverPlugin(driver, 'memory'));
// ...
await kernel.use(new MSWPlugin({ /* ... */ }));
await kernel.bootstrap();
```

---

## Next Steps

- See [Security Guide](/docs/guides/security) for authorization and permissions
Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/business-logic.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ export const contractExpirationCheck: Flow = {
| `script` | Run an inline expression / function |
| `loop`, `map` | Iterate over a collection |
| `create_record`, `update_record`, `delete_record`, `get_record` | CRUD |
| `http` | Outbound HTTP call (`http_request` is a deprecated alias) |
| `http` | Outbound HTTP call |
| `connector_action` | Invoke a registered connector action |
| `notify` | In-app/email-style notification dispatch |
| `wait`, `screen`, `approval` | Durable pauses |
Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/client-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -382,7 +382,7 @@ The `find` method accepts an options object with **canonical** (recommended) fie
| `expand` | `Record<string, any>` or `string[]` | Relation loading (JOIN) | `{ owner: {} }` |

<Callout type="warn">
**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`.
**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`).
</Callout>

### Batch Options
Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/contracts/metadata-service.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ console.log(result.failed); // failed

## UI Metadata (Views & Dashboards)

UI metadata types (`view`, `dashboard`, `page`, `app`, `theme`) are first-class citizens in the Metadata Service. The previously separate `IUIService` has been deprecated.
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.

### Reading UI Metadata

Expand Down
67 changes: 6 additions & 61 deletions content/docs/guides/deployment-vercel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,15 @@ description: Deploy ObjectStack applications to Vercel — Server mode (recommen

# Deploy to Vercel

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.
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`).

<Callout type="warn">
**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.
</Callout>

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

---

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

### Option A: Next.js + `@objectstack/nextjs`

This is the recommended approach for Vercel. The `@objectstack/nextjs` adapter maps all ObjectStack protocol endpoints to a single Next.js catch-all route.

**1. Create the kernel singleton:**

```typescript
// lib/kernel.ts
import { ObjectKernel, DriverPlugin, AppPlugin } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectstack/objectql';
import appConfig from '../objectstack.config';

let kernel: ObjectKernel | null = null;

export async function getKernel() {
if (kernel) return kernel;

kernel = new ObjectKernel();
await kernel.use(new ObjectQLPlugin());

// Use your production driver (Postgres, MongoDB, etc.)
// await kernel.use(new DriverPlugin(new PostgresDriver({
// url: process.env.DATABASE_URL,
// })));

// Load the application configuration (objects, data, etc.)
await kernel.use(new AppPlugin(appConfig));

await kernel.bootstrap();
return kernel;
}
```

**2. Create the API route handler:**

```typescript
// app/api/[...objectstack]/route.ts
import { createRouteHandler } from '@objectstack/nextjs';
import { getKernel } from '@/lib/kernel';

async function handler(...args: any[]) {
const kernel = await getKernel();
const routeHandler = createRouteHandler({ kernel, prefix: '/api' });
return routeHandler(...args);
}

export { handler as GET, handler as POST, handler as PATCH, handler as DELETE };
```

**3. `vercel.json` (optional — Next.js works out of the box):**

```json
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"framework": "nextjs"
}
```

### Option B: Hono + `@objectstack/hono` (Vite SPA)
### Hono serverless function (`@objectstack/hono`)

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.

Expand Down
9 changes: 4 additions & 5 deletions content/docs/guides/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -275,14 +275,15 @@ the hosted ObjectStack Cloud control plane.

## Legacy aliases

The names below still work this release but emit a one-shot deprecation
warning. They will be removed in a future major.
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_*`.

> **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`.

| Canonical | Legacy |
|:---|:---|
| `OS_PORT` | `PORT` |
| `OS_DATABASE_URL` | `DATABASE_URL` |
| `OS_AUTH_URL` | `BETTER_AUTH_URL`, `AUTH_BASE_URL`, `OS_AUTH_BASE_URL` |
| `OS_AUTH_URL` | `BETTER_AUTH_URL` |
| `OS_AUTH_SECRET` | `BETTER_AUTH_SECRET`, `AUTH_SECRET` |
| `OS_ROOT_DOMAIN` | `ROOT_DOMAIN` |
| `OS_CORS_ENABLED` | `CORS_ENABLED` |
Expand All @@ -293,8 +294,6 @@ warning. They will be removed in a future major.
| `OS_MCP_SERVER_ENABLED` | `MCP_SERVER_ENABLED` |
| `OS_MCP_SERVER_NAME` | `MCP_SERVER_NAME` |
| `OS_MCP_SERVER_TRANSPORT` | `MCP_SERVER_TRANSPORT` |
| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` |
| `OS_NODE_ID` | `OBJECTSTACK_NODE_ID` |
| `OS_METADATA_WRITABLE` | `OBJECTSTACK_METADATA_WRITABLE` |
| `OS_HOME` | `OBJECTSTACK_HOME` |
| `OS_DEV_CRYPTO_KEY` | `OBJECTSTACK_DEV_CRYPTO_KEY` |
4 changes: 2 additions & 2 deletions content/docs/guides/metadata/flow.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Each node performs a specific action in the flow.
| `update_record` | Update existing records |
| `delete_record` | Delete records |
| `get_record` | Query records |
| `http` | Make an HTTP API call (the deprecated alias `http_request` still resolves to this) |
| `http` | Make an HTTP API call |
| `script` | Run a custom script action (dispatched by `config.actionType`) |
| `screen` | Display a user form/screen (durable pause) |
| `wait` | Pause for a timer or named signal (durable pause; timers auto-resume) |
Expand Down Expand Up @@ -317,7 +317,7 @@ events).
type: 'try_catch',
label: 'Charge with fallback',
config: {
try: { nodes: [{ id: 'charge', type: 'http_request', label: 'Charge', config: { /* … */ } }], edges: [] },
try: { nodes: [{ id: 'charge', type: 'http', label: 'Charge', config: { /* … */ } }], edges: [] },
catch: { nodes: [{ id: 'flag', type: 'update_record', label: 'Flag failure', config: { /* … */ } }], edges: [] },
errorVariable: '$error',
retry: { maxRetries: 3, retryDelayMs: 1000, backoffMultiplier: 2 },
Expand Down
Loading