Skill v1.0.1

currentAutomated scan100/100

majiayu000/claude-skill-registry-data/bknd-deploy-hosting-cameronapak-freedom-stack-v3-2

3 files

──Details

PublishedMay 23, 2026 at 04:26 PM

Content Hashsha256:7ca0ed3feae12535...

Git SHA56773ea772f3

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 10.4 KB)

SKILL.md10.4 KBactive

SKILL.md · 551 lines · 10.4 KB

version: "1.0.1" name: bknd-deploy-hosting description: Use when deploying a Bknd application to production hosting. Covers Cloudflare Workers/Pages, Node.js/Bun servers, Docker, Vercel, AWS Lambda, and other platforms.

Deploy to Hosting

Deploy your Bknd application to various hosting platforms.

Prerequisites

Working Bknd application locally
Schema defined and tested
Database provisioned (see bknd-database-provision)
Environment variables prepared (see bknd-env-config)

When to Use UI Mode

Cloudflare/Vercel dashboards for environment variables
Platform-specific deployment settings
Viewing deployment logs

When to Use Code Mode

All deployment configuration and commands
Adapter setup for target platform
CI/CD pipeline configuration

Platform Selection Guide

Platform	Best For	Database Options	Cold Start
Cloudflare Workers	Edge, global low-latency	D1, Turso	~0ms
Cloudflare Pages	Static + API	D1, Turso	~0ms
Vercel	Next.js apps	Turso, Neon	~200ms
Node.js/Bun VPS	Full control, dedicated	Any	N/A
Docker	Containerized, portable	Any	N/A
AWS Lambda	Serverless, pay-per-use	Turso, RDS	~500ms

Code Approach

Cloudflare Workers

Step 1: Install Wrangler

bash

npm install -D wrangler

Step 2: Create `wrangler.toml`

toml

name = "my-bknd-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"
 
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-d1-database-id"
 
# Optional: R2 for media storage
[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "my-bucket"
 
[vars]
ENVIRONMENT = "production"

Step 3: Configure Adapter

typescript

// src/index.ts
import { hybrid, type CloudflareBkndConfig } from "bknd/adapter/cloudflare";
import { d1Sqlite } from "bknd/adapter/cloudflare";
import { em, entity, text } from "bknd";
const schema = em({
  posts: entity("posts", {
    title: text().required(),
  }),
});
export default hybrid<CloudflareBkndConfig>({
  app: (env) => ({
    connection: d1Sqlite({ binding: env.DB }),
    schema,
    isProduction: true,
    auth: {
      jwt: {
        secret: env.JWT_SECRET,
      },
    },
    config: {
      media: {
        enabled: true,
        adapter: {
          type: "r2",
          config: { bucket: env.R2_BUCKET },
        },
      },
    },
  }),
});

Step 4: Create D1 Database

bash

# Create database
wrangler d1 create my-database
 
# Copy the database_id to wrangler.toml

Step 5: Set Secrets

bash

wrangler secret put JWT_SECRET
# Enter your secret (min 32 chars)

Step 6: Deploy

bash

wrangler deploy

Cloudflare Pages (with Functions)

Step 1: Create `functions/api/[[bknd]].ts`

typescript

import { hybrid, type CloudflareBkndConfig } from "bknd/adapter/cloudflare";
import { d1Sqlite } from "bknd/adapter/cloudflare";
import schema from "../../bknd.config";
export const onRequest = hybrid<CloudflareBkndConfig>({
  app: (env) => ({
    connection: d1Sqlite({ binding: env.DB }),
    schema,
    isProduction: true,
    auth: {
      jwt: { secret: env.JWT_SECRET },
    },
  }),
});

Step 2: Configure Pages

In Cloudflare dashboard:

Connect your git repository
Set build command (if any)
Add D1 binding under Settings > Functions > D1 Database Bindings
Add environment variables under Settings > Environment Variables

Node.js / Bun (VPS)

Step 1: Create Production Entry

typescript

// index.ts
import { serve, type BunBkndConfig } from "bknd/adapter/bun";
// or for Node.js:
// import { serve } from "bknd/adapter/node";
const config: BunBkndConfig = {
  connection: {
    url: process.env.DB_URL!,
    authToken: process.env.DB_TOKEN,
  },
  isProduction: true,
  auth: {
    jwt: {
      secret: process.env.JWT_SECRET!,
      expires: "7d",
    },
  },
  config: {
    media: {
      enabled: true,
      adapter: {
        type: "s3",
        config: {
          bucket: process.env.S3_BUCKET!,
          region: process.env.S3_REGION!,
          accessKeyId: process.env.S3_ACCESS_KEY!,
          secretAccessKey: process.env.S3_SECRET_KEY!,
        },
      },
    },
    guard: {
      enabled: true,
    },
  },
};
serve(config);

Step 2: Set Environment Variables

bash

export DB_URL="libsql://your-db.turso.io"
export DB_TOKEN="your-turso-token"
export JWT_SECRET="your-32-char-minimum-secret"
export PORT=3000

Step 3: Run with Process Manager

bash

# Using PM2
npm install -g pm2
pm2 start "bun run index.ts" --name bknd-app
 
# Or systemd (create /etc/systemd/system/bknd.service)

Docker

Step 1: Create `Dockerfile`

dockerfile

FROM oven/bun:1.0-alpine
 
WORKDIR /app
 
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
 
COPY . .
 
# Create data directory for SQLite (if using file-based)
RUN mkdir -p /app/data
 
ENV PORT=3000
 
EXPOSE 3000
 
CMD ["bun", "run", "index.ts"]

Step 2: Create `docker-compose.yml`

yaml

version: "3.8"
services:
  bknd:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - bknd-data:/app/data
    environment:
      - DB_URL=file:/app/data/bknd.db
      - JWT_SECRET=${JWT_SECRET}
      - NODE_ENV=production
    restart: unless-stopped
 
volumes:
  bknd-data:

Step 3: Deploy

bash

# Build and run
docker compose up -d
 
# View logs
docker compose logs -f bknd

Vercel (Next.js)

Step 1: Create API Route

typescript

// app/api/bknd/[[...bknd]]/route.ts
export { GET, POST, PUT, DELETE, PATCH } from "bknd/adapter/nextjs";

Step 2: Create `bknd.config.ts`

typescript

import type { NextjsBkndConfig } from "bknd/adapter/nextjs";
import { em, entity, text } from "bknd";
const schema = em({
  posts: entity("posts", {
    title: text().required(),
  }),
});
type Database = (typeof schema)["DB"];
declare module "bknd" {
  interface DB extends Database {}
}
export default {
  app: (env) => ({
    connection: {
      url: env.DB_URL,
      authToken: env.DB_TOKEN,
    },
    schema,
    isProduction: env.NODE_ENV === "production",
    auth: {
      jwt: { secret: env.JWT_SECRET },
    },
  }),
} satisfies NextjsBkndConfig;

Step 3: Set Vercel Environment Variables

In Vercel dashboard or CLI:

bash

vercel env add DB_URL
vercel env add DB_TOKEN
vercel env add JWT_SECRET

Step 4: Deploy

bash

vercel deploy --prod

AWS Lambda

Step 1: Install Dependencies

bash

npm install -D serverless serverless-esbuild

Step 2: Create `handler.ts`

typescript

import { createHandler } from "bknd/adapter/aws";
export const handler = createHandler({
  connection: {
    url: process.env.DB_URL!,
    authToken: process.env.DB_TOKEN,
  },
  isProduction: true,
  auth: {
    jwt: { secret: process.env.JWT_SECRET! },
  },
});

Step 3: Create `serverless.yml`

yaml

service: bknd-api
 
provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  environment:
    DB_URL: ${env:DB_URL}
    DB_TOKEN: ${env:DB_TOKEN}
    JWT_SECRET: ${env:JWT_SECRET}
 
plugins:
  - serverless-esbuild
 
functions:
  api:
    handler: handler.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY
      - http:
          path: /
          method: ANY

Step 4: Deploy

bash

serverless deploy --stage prod

Pre-Deployment Checklist

bash

# 1. Generate types
npx bknd types
 
# 2. Test locally with production-like config
DB_URL="your-prod-db" JWT_SECRET="your-secret" npx bknd run
 
# 3. Verify schema sync
# Schema auto-syncs on first request in production

Environment Variables (All Platforms)

Variable	Required	Description
`DB_URL`	Yes	Database connection URL
`DB_TOKEN`	Depends	Auth token (Turso/LibSQL)
`JWT_SECRET`	Yes	Min 32 chars for security
`PORT`	No	Server port (default: 3000)

Common Pitfalls

"Module not found" for Native SQLite

Problem: better-sqlite3 not available in serverless

Fix: Use LibSQL/Turso instead of file-based SQLite:

typescript

connection: {
  url: "libsql://your-db.turso.io",
  authToken: process.env.DB_TOKEN,
}

"JWT_SECRET required" Error

Problem: Auth fails in production

Fix: Set JWT_SECRET environment variable:

bash

# Cloudflare
wrangler secret put JWT_SECRET
 
# Vercel
vercel env add JWT_SECRET
 
# Docker
docker run -e JWT_SECRET="your-secret" ...

Cold Start Timeouts (Lambda)

Problem: First request times out

Fix:

Use lighter database (Turso over RDS)
Reduce bundle size
Enable provisioned concurrency for critical functions

D1 Binding Not Found

Problem: env.DB is undefined

Fix: Check wrangler.toml D1 binding:

toml

[[d1_databases]]
binding = "DB"  # Must match env.DB in code
database_name = "my-database"
database_id = "actual-id-from-wrangler-d1-create"

Media Uploads Fail in Serverless

Problem: Local storage doesn't work in serverless

Fix: Use cloud storage adapter:

typescript

config: {
  media: {
    adapter: {
      type: "s3",  // or "r2", "cloudinary"
      config: { /* credentials */ },
    },
  },
}

CORS Errors

Problem: Frontend can't access API

Fix: Configure CORS in your adapter:

typescript

// Most adapters handle this automatically
// For custom needs, check platform docs

Deployment Commands Reference

bash

# Cloudflare Workers
wrangler deploy
wrangler tail  # View logs
 
# Vercel
vercel deploy --prod
vercel logs
 
# Docker
docker compose up -d
docker compose logs -f
 
# AWS Lambda
serverless deploy --stage prod
serverless logs -f api

DOs and DON'Ts

DO:

Set isProduction: true in production config
Use cloud storage (S3/R2/Cloudinary) for media
Set strong JWT_SECRET (min 32 chars)
Enable Guard for authorization
Test with production database before deploying
Use environment variables for all secrets

DON'T:

Use file-based SQLite in serverless
Hardcode secrets in code
Deploy without testing schema sync
Use local storage adapter in production
Skip JWT_SECRET configuration
Commit .env files with real secrets

Related Skills

bknd-database-provision - Set up production database
bknd-production-config - Production security settings
bknd-storage-config - Configure media storage
bknd-env-config - Environment variable setup
bknd-local-setup - Local development (pre-deploy testing)

← v1.0.0 All versions