|
1 | 1 | --- |
2 | 2 | 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. |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # Deploy to Vercel |
7 | 7 |
|
8 | 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 | 9 |
|
10 | 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. |
| 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. |
12 | 12 | </Callout> |
13 | 13 |
|
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 | | - |
185 | 14 | --- |
186 | 15 |
|
187 | 16 | ## Server Mode (Serverless Functions) |
@@ -302,7 +131,7 @@ Configure these in Vercel Project Settings → Environment Variables: |
302 | 131 |
|
303 | 132 | | Variable | Description | |
304 | 133 | | :--- | :--- | |
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. | |
306 | 135 | | `VITE_SERVER_URL` | Backend API URL (empty for same-origin) | |
307 | 136 |
|
308 | 137 | ### Cloud control plane |
@@ -336,54 +165,20 @@ storage for artifacts. |
336 | 165 |
|
337 | 166 | --- |
338 | 167 |
|
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 | | - |
350 | 168 | ## Deployment Checklist |
351 | 169 |
|
352 | | -### Server Mode (Recommended) |
353 | | - |
354 | 170 | - [ ] `api/index.ts` Hono entrypoint exists with `handle(app)` export |
355 | 171 | - [ ] `api/_kernel.ts` boots the kernel with the correct driver |
356 | 172 | - [ ] `vercel.json` sets `VITE_USE_MOCK_SERVER=false` and `VITE_SERVER_URL=` (empty) |
357 | 173 | - [ ] Rewrite rule routes `/api/*` to `/api` and excludes `/api/` from SPA rewrite |
358 | 174 | - [ ] `DATABASE_URL` is configured in Vercel environment variables (for production drivers) |
359 | 175 | - [ ] CORS is configured if frontend and API are on different origins |
360 | 176 |
|
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 | | - |
382 | 177 | --- |
383 | 178 |
|
384 | 179 | ## Related |
385 | 180 |
|
386 | | -- [Plugin System](/docs/guides/plugins) — MSW and Hono server plugins |
| 181 | +- [Plugin System](/docs/guides/plugins) — the Hono server adapter |
387 | 182 | - [Client SDK](/docs/guides/client-sdk) — Frontend data fetching |
388 | 183 | - [Driver Configuration](/docs/guides/driver-configuration) — Database setup |
389 | 184 | - [Architecture](/docs/getting-started/architecture) — Kernel and runtime overview |
0 commit comments