Skip to content

Commit 4759412

Browse files
Claudexuyushun441-sys
Claude
and
xuyushun441-sys
authored
docs: add deployment documentation and Vercel deploy button
Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/cc91e2f2-a734-4a52-b865-5fa83a86e934 Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
1 parent 33c7ce3 commit 4759412

File tree

3 files changed

+172
-0
lines changed

3 files changed

+172
-0
lines changed

‎examples/app-host/.vercelignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Ignore build artifacts
2+
dist/
3+
.turbo/
4+
5+
# Ignore test files
6+
test/
7+
*.test.ts
8+
*.spec.ts
9+
10+
# Ignore development files
11+
debug-registry.ts
12+
src/
13+
14+
# Ignore source files (only need the bundle)
15+
server/
16+
scripts/bundle-api.mjs
17+
18+
# Ignore metadata (using in-memory driver)
19+
metadata/
20+
21+
# Keep only the bundled API handler
22+
!api/_handler.js
23+
!api/_handler.js.map
24+
!api/[[...route]].js

‎examples/app-host/DEPLOYMENT.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Deploying App Host to Vercel
2+
3+
This example demonstrates how to deploy the ObjectStack app-host to Vercel using Hono.
4+
5+
## Prerequisites
6+
7+
1. A Vercel account
8+
2. Vercel CLI installed (optional): `npm i -g vercel`
9+
10+
## Environment Variables
11+
12+
Set the following environment variables in your Vercel project:
13+
14+
- `AUTH_SECRET`: A secure random string (minimum 32 characters) for authentication
15+
16+
## Deployment Steps
17+
18+
### Option 1: Using Vercel CLI
19+
20+
1. Install Vercel CLI:
21+
```bash
22+
npm i -g vercel
23+
```
24+
25+
2. Navigate to the app-host directory:
26+
```bash
27+
cd examples/app-host
28+
```
29+
30+
3. Deploy to Vercel:
31+
```bash
32+
vercel
33+
```
34+
35+
4. Set environment variables:
36+
```bash
37+
vercel env add AUTH_SECRET
38+
```
39+
40+
### Option 2: Using Vercel Dashboard
41+
42+
1. Import the repository to Vercel
43+
2. Set the root directory to `examples/app-host`
44+
3. Add environment variables in the project settings
45+
4. Deploy
46+
47+
## Build Configuration
48+
49+
The build is configured in `vercel.json`:
50+
51+
- **Install Command**: `cd ../.. && pnpm install` (installs monorepo dependencies)
52+
- **Build Command**: `bash scripts/build-vercel.sh` (builds and bundles the application)
53+
- **Framework**: `null` (uses custom build setup)
54+
55+
## How It Works
56+
57+
1. **Build Process** (`scripts/build-vercel.sh`):
58+
- Builds the TypeScript project using Turbo
59+
- Bundles the server code using esbuild (`scripts/bundle-api.mjs`)
60+
- Copies native dependencies (like better-sqlite3) to local node_modules
61+
62+
2. **API Handler** (`api/[[...route]].js`):
63+
- Committed catch-all route handler that Vercel detects pre-build
64+
- Delegates to the bundled handler (`api/_handler.js`)
65+
66+
3. **Server Entrypoint** (`server/index.ts`):
67+
- Boots ObjectStack kernel with Hono adapter
68+
- Uses `@hono/node-server`'s `getRequestListener()` for Vercel compatibility
69+
- Handles Vercel's pre-buffered request body properly
70+
71+
4. **Hono Integration**:
72+
- Uses `@objectstack/hono` adapter to create the HTTP application
73+
- Provides REST API at `/api/v1` prefix
74+
- Includes authentication via AuthPlugin
75+
76+
## Architecture
77+
78+
The deployment follows Vercel's serverless function pattern:
79+
80+
```
81+
examples/app-host/
82+
├── api/
83+
│ ├── [[...route]].js # Committed entry point
84+
│ └── _handler.js # Generated bundle (not committed)
85+
├── server/
86+
│ └── index.ts # Server implementation
87+
├── scripts/
88+
│ ├── build-vercel.sh # Build script
89+
│ └── bundle-api.mjs # Bundler configuration
90+
├── .npmrc # pnpm configuration (node-linker=hoisted)
91+
└── vercel.json # Vercel configuration
92+
```
93+
94+
## Testing Locally
95+
96+
Before deploying, you can test locally:
97+
98+
```bash
99+
# Build the application
100+
pnpm build
101+
102+
# Run in development mode
103+
pnpm dev
104+
105+
# Test the API
106+
curl http://localhost:3000/api/v1/discovery
107+
```
108+
109+
## Accessing the API
110+
111+
After deployment, your API will be available at:
112+
113+
- Discovery: `https://your-app.vercel.app/api/v1/discovery`
114+
- Data API: `https://your-app.vercel.app/api/v1/data/:object`
115+
- Meta API: `https://your-app.vercel.app/api/v1/meta/:type`
116+
117+
## Troubleshooting
118+
119+
### Build Fails
120+
121+
- Ensure all dependencies are installed: `pnpm install`
122+
- Check build logs in Vercel dashboard
123+
- Verify `build-vercel.sh` is executable: `chmod +x scripts/build-vercel.sh`
124+
125+
### Runtime Errors
126+
127+
- Check function logs in Vercel dashboard
128+
- Verify environment variables are set correctly
129+
- Ensure `AUTH_SECRET` is at least 32 characters
130+
131+
### Module Not Found
132+
133+
- The build script copies native modules to local node_modules
134+
- Check that `better-sqlite3` is in dependencies
135+
- Verify `vercel.json` includeFiles pattern matches the module
136+
137+
## References
138+
139+
- [Vercel Hono Documentation](https://vercel.com/docs/frameworks/backend/hono)
140+
- [ObjectStack Documentation](../../README.md)
141+
- [Hono Documentation](https://hono.dev/)

‎examples/app-host/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,20 @@
33
This is a reference implementation of the ObjectStack Server Protocol (Kernel).
44
It demonstrates how to build a metadata-driven backend that dynamically loads object definitions from plugins and automatically generates REST APIs.
55

6+
## Deployment
7+
8+
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/objectstack-ai/framework/tree/main/examples/app-host&project-name=objectstack-app-host&repository-name=objectstack-app-host)
9+
10+
See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed deployment instructions.
11+
612
## Features
713

814
- **Dynamic Schema Loading**: Loads `crm` and `todo` apps as plugins.
915
- **Unified Metadata API**: `/api/v1/meta/objects`
1016
- **Unified Data API**: `/api/v1/data/:object` (CRUD)
1117
- **Zero-Code Backend**: No creating routes or controllers per object.
1218
- **Preview Mode**: Run in demo mode — bypass login, auto-simulate admin identity.
19+
- **Vercel Deployment**: Ready-to-deploy to Vercel with Hono adapter.
1320

1421
## Setup
1522

0 commit comments

Comments
 (0)