Skip to content

Commit dc619af

Browse files
os-zhuangclaude
andauthored
docs(content): finish the 11 docs alignment — drop MSW mode from the Vercel guide (#2399)
Closes the two deferred items from the docs-site pass (#2398 / #2392): - deployment-vercel.mdx: removed the entire MSW Mode section and all its references (intro table, "Choosing the Mode", the MSW checklist subsection, the Comparison table) — `@objectstack/plugin-msw` is gone. Hono server mode is now the single documented path; a short callout notes the removal. - implementation-status.mdx: QA table `@objectstack/plugin-msw` column → `@objectstack/verify` (the actual test harness). content/docs/** now has no removed-package references (only an intentional "removed in 11" callout). MDX validated by Build Docs. Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 11b9e4d commit dc619af

2 files changed

Lines changed: 5 additions & 210 deletions

File tree

content/docs/concepts/implementation-status.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -341,7 +341,7 @@ cloud / EE.
341341

342342
## QA & Testing
343343

344-
| Protocol | @objectstack/spec | @objectstack/core | @objectstack/plugin-msw | Status |
344+
| Protocol | @objectstack/spec | @objectstack/core | @objectstack/verify | Status |
345345
|:---------|:-----------------:|:-----------------:|:-----------------------:|:------:|
346346
| **Testing** |||| ✅ Full |
347347

Lines changed: 4 additions & 209 deletions
Original file line numberDiff line numberDiff line change
@@ -1,187 +1,16 @@
11
---
22
title: Deploy to Vercel
3-
description: Deploy ObjectStack applications to Vercel — Server mode (recommended) for real API endpoints or MSW mode for static demos
3+
description: Deploy ObjectStack applications to Vercel with the Hono server adapter.
44
---
55

66
# Deploy to Vercel
77

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

1010
<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.
11+
**Removed in 11.** The in-browser MSW mode (`@objectstack/plugin-msw`) and the Next.js adapter (`@objectstack/nextjs`) are no longer published — use the Hono server path below.
1212
</Callout>
1313

14-
| Mode | Runtime | Vercel Feature | Use Case |
15-
| :--- | :--- | :--- | :--- |
16-
| **Server** (default) | Node.js / Edge | Serverless Functions | Production apps, Studio, real database |
17-
18-
---
19-
20-
## MSW Mode (Static SPA)
21-
22-
In MSW mode the entire ObjectStack kernel runs **in the browser**. Mock Service Worker intercepts `fetch` calls and routes them to an in-memory ObjectQL engine — no backend required.
23-
24-
### How It Works
25-
26-
```
27-
┌─────────────────────────── Browser ───────────────────────────┐
28-
│ React App → fetch('/api/v1/data/task') │
29-
│ ↓ │
30-
│ MSW Service Worker (intercepts request) │
31-
│ ↓ │
32-
│ ObjectKernel → ObjectQL → InMemoryDriver │
33-
│ ↓ │
34-
│ JSON Response → React App │
35-
└───────────────────────────────────────────────────────────────┘
36-
```
37-
38-
### Project Setup
39-
40-
```typescript
41-
// objectstack.config.ts
42-
import { defineStack } from '@objectstack/spec';
43-
import * as objects from './src/objects';
44-
45-
export default defineStack({
46-
manifest: {
47-
id: 'com.example.myapp',
48-
name: 'My App',
49-
version: '1.0.0',
50-
type: 'app',
51-
},
52-
objects: Object.values(objects),
53-
data: [
54-
{
55-
object: 'task',
56-
mode: 'upsert',
57-
externalId: 'subject',
58-
records: [
59-
{ subject: 'Learn ObjectStack', status: 'in_progress', priority: 'high' },
60-
],
61-
},
62-
],
63-
});
64-
```
65-
66-
### Kernel Bootstrap (Browser)
67-
68-
Create a kernel factory that boots the entire stack in the browser:
69-
70-
```typescript
71-
// src/mocks/createKernel.ts
72-
import { ObjectKernel, DriverPlugin, AppPlugin } from '@objectstack/runtime';
73-
import { ObjectQLPlugin } from '@objectstack/objectql';
74-
import { InMemoryDriver } from '@objectstack/driver-memory';
75-
import { MSWPlugin } from '@objectstack/plugin-msw';
76-
77-
export async function createKernel(appConfigs: any[]) {
78-
const kernel = new ObjectKernel();
79-
80-
await kernel.use(new ObjectQLPlugin());
81-
await kernel.use(new DriverPlugin(new InMemoryDriver(), 'memory'));
82-
83-
for (const config of appConfigs) {
84-
await kernel.use(new AppPlugin(config));
85-
}
86-
87-
await kernel.use(new MSWPlugin({
88-
enableBrowser: true,
89-
baseUrl: '/api/v1',
90-
logRequests: true,
91-
}));
92-
93-
await kernel.bootstrap();
94-
return kernel;
95-
}
96-
```
97-
98-
### Entry Point
99-
100-
```typescript
101-
// src/main.tsx
102-
import appConfig from '../objectstack.config';
103-
import { createKernel } from './mocks/createKernel';
104-
105-
async function bootstrap() {
106-
// Boot the in-browser kernel before rendering
107-
await createKernel([appConfig]);
108-
109-
// Now render — all fetch('/api/v1/...') calls are intercepted by MSW
110-
ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
111-
}
112-
113-
bootstrap();
114-
```
115-
116-
### Vite Configuration
117-
118-
MSW requires the Service Worker file in your `public/` directory. Add the init script and configure Vite:
119-
120-
```bash
121-
# Generate the MSW Service Worker file
122-
npx msw init public --save
123-
```
124-
125-
```typescript
126-
// vite.config.ts
127-
import { defineConfig } from 'vite';
128-
import react from '@vitejs/plugin-react';
129-
130-
export default defineConfig({
131-
plugins: [react()],
132-
optimizeDeps: {
133-
include: ['msw', 'msw/browser', '@objectstack/spec'],
134-
},
135-
});
136-
```
137-
138-
### `vercel.json`
139-
140-
```json
141-
{
142-
"$schema": "https://openapi.vercel.sh/vercel.json",
143-
"framework": "vite",
144-
"buildCommand": "vite build",
145-
"outputDirectory": "dist",
146-
"build": {
147-
"env": {
148-
"VITE_USE_MOCK_SERVER": "true"
149-
}
150-
},
151-
"rewrites": [
152-
{ "source": "/(.*)", "destination": "/index.html" }
153-
]
154-
}
155-
```
156-
157-
<Callout type="info">
158-
The `rewrites` rule is essential for SPA routing — it ensures all paths serve `index.html` so the client-side router can handle navigation.
159-
</Callout>
160-
161-
### Monorepo Configuration
162-
163-
If your project lives in a monorepo (e.g. pnpm workspaces + Turborepo), update the install and build commands:
164-
165-
```json
166-
{
167-
"$schema": "https://openapi.vercel.sh/vercel.json",
168-
"framework": "vite",
169-
"installCommand": "cd ../.. && pnpm install",
170-
"buildCommand": "cd ../.. && pnpm turbo run build --filter=@myorg/my-app",
171-
"outputDirectory": "dist",
172-
"build": {
173-
"env": {
174-
"VITE_USE_MOCK_SERVER": "true"
175-
}
176-
},
177-
"rewrites": [
178-
{ "source": "/(.*)", "destination": "/index.html" }
179-
]
180-
}
181-
```
182-
183-
Set the **Root Directory** in Vercel project settings to the app's folder (e.g. `apps/my-app`).
184-
18514
---
18615

18716
## Server Mode (Serverless Functions)
@@ -302,7 +131,7 @@ Configure these in Vercel Project Settings → Environment Variables:
302131

303132
| Variable | Description |
304133
| :--- | :--- |
305-
| `VITE_USE_MOCK_SERVER` | `true` = in-browser MSW kernel; `false` = real backend. A **build-time** flag baked into the SPA bundle. |
134+
| `VITE_USE_MOCK_SERVER` | Leave `false` — the SPA talks to a real backend at `VITE_SERVER_URL`. (The `true` in-browser mock mode was removed in 11.) A **build-time** flag baked into the SPA bundle. |
306135
| `VITE_SERVER_URL` | Backend API URL (empty for same-origin) |
307136

308137
### Cloud control plane
@@ -336,54 +165,20 @@ storage for artifacts.
336165

337166
---
338167

339-
## Choosing the Mode
340-
341-
The mode is selected at **build time** via the `VITE_USE_MOCK_SERVER` flag, which is baked into the SPA bundle:
342-
343-
- `VITE_USE_MOCK_SERVER=true` → the in-browser MSW kernel (static demo).
344-
- `VITE_USE_MOCK_SERVER=false` → the SPA talks to a real backend at `VITE_SERVER_URL` (empty = same-origin).
345-
346-
Because the flag is compiled into the bundle, there is no runtime `?mode=` URL switch — to change modes you must rebuild with the desired value.
347-
348-
---
349-
350168
## Deployment Checklist
351169

352-
### Server Mode (Recommended)
353-
354170
- [ ] `api/index.ts` Hono entrypoint exists with `handle(app)` export
355171
- [ ] `api/_kernel.ts` boots the kernel with the correct driver
356172
- [ ] `vercel.json` sets `VITE_USE_MOCK_SERVER=false` and `VITE_SERVER_URL=` (empty)
357173
- [ ] Rewrite rule routes `/api/*` to `/api` and excludes `/api/` from SPA rewrite
358174
- [ ] `DATABASE_URL` is configured in Vercel environment variables (for production drivers)
359175
- [ ] CORS is configured if frontend and API are on different origins
360176

361-
### MSW Mode (Static Demo)
362-
363-
- [ ] `msw init public --save` has been run (Service Worker in `public/`)
364-
- [ ] `vercel.json` specifies `"framework": "vite"` and SPA rewrites
365-
- [ ] `VITE_USE_MOCK_SERVER=true` is set in build environment
366-
- [ ] Seed data is defined in `objectstack.config.ts` (`data` array)
367-
368-
---
369-
370-
## Comparison
371-
372-
| Feature | MSW Mode | Server Mode |
373-
| :--- | :--- | :--- |
374-
| **Database** | In-memory (browser) | PostgreSQL, MongoDB, etc. |
375-
| **Data Persistence** | Per session (lost on refresh) | Persistent |
376-
| **Cold Start** | None (client-side) | ~200ms (Serverless) |
377-
| **Offline Support** | ✅ Full | ❌ Requires network |
378-
| **Multi-user** | ❌ Single user | ✅ Full |
379-
| **Cost** | Free (static hosting) | Pay per invocation |
380-
| **Best For** | Demos, prototypes, docs | Production applications |
381-
382177
---
383178

384179
## Related
385180

386-
- [Plugin System](/docs/guides/plugins)MSW and Hono server plugins
181+
- [Plugin System](/docs/guides/plugins)the Hono server adapter
387182
- [Client SDK](/docs/guides/client-sdk) — Frontend data fetching
388183
- [Driver Configuration](/docs/guides/driver-configuration) — Database setup
389184
- [Architecture](/docs/getting-started/architecture) — Kernel and runtime overview

0 commit comments

Comments
 (0)