Deployment

Overview

Better-T-Stack projects can be deployed to various platforms. The CLI provides built-in support for Cloudflare Workers deployment via Alchemy, and generated projects are compatible with other platforms.

Cloudflare Workers deployment

What is Cloudflare Workers?

Cloudflare Workers is a serverless platform that runs your code on Cloudflare’s global edge network (300+ locations). It uses V8 isolates for near-zero cold starts. Benefits:

Global edge distribution
Sub-millisecond cold starts
Native TypeScript support
Generous free tier
Integrated with D1, R2, KV, Durable Objects

Enabling Cloudflare deployment

Web app deployment:

npm create better-t-stack@latest my-app \
  --frontend tanstack-start \
  --web-deploy cloudflare

Server API deployment:

npm create better-t-stack@latest my-app \
  --backend hono \
  --runtime workers \
  --server-deploy cloudflare

Combined (web + server):

npm create better-t-stack@latest my-app \
  --frontend tanstack-router \
  --backend hono \
  --runtime workers \
  --web-deploy cloudflare \
  --server-deploy cloudflare

What you get

When Cloudflare deployment is enabled, Better-T-Stack generates:

packages/infra/
  alchemy.run.ts          (Infrastructure as code)
  .env                    (Environment configuration)
  package.json            (Alchemy dependencies)

The alchemy.run.ts file defines your entire infrastructure:

Workers for web and/or server
D1 databases (if using SQLite)
Environment variables and secrets
Deployment configuration

See the Cloudflare with Alchemy guide for complete details.

Deployment commands

Deploy to production:

bun run deploy

Deploy to specific stage:

bun run deploy --stage prod
bun run deploy --stage staging

Development mode (local):

bun run dev

Destroy resources:

bun run destroy
bun run destroy --stage staging

Environment setup

Before deploying:

Add environment variables

Create or update .env files:

# packages/infra/.env
ALCHEMY_PASSWORD=your-secure-password
CORS_ORIGIN=https://your-app.workers.dev
VITE_SERVER_URL=https://your-server.workers.dev

Add secrets

For sensitive values:

# packages/infra/.env
BETTER_AUTH_SECRET=your-secret-key
DATABASE_URL=your-database-url
API_KEY=your-api-key

These are encrypted by Alchemy using ALCHEMY_PASSWORD.

Configure Cloudflare

Ensure you have:

Cloudflare account
API token with Workers permissions
Workers subdomain configured

Deploy

bun run deploy

First deploy creates all resources and outputs URLs:

Web    -> https://my-app-web.your-subdomain.workers.dev
Server -> https://my-app-server.your-subdomain.workers.dev

Multi-stage deployments

Deploy to multiple environments (dev, staging, prod): Environment variables method:

# packages/infra/.env.prod
ALCHEMY_STAGE=prod
CORS_ORIGIN=https://myapp.com

bun run deploy --env-file .env.prod

CLI argument method:

bun run deploy --stage dev
bun run deploy --stage staging  
bun run deploy --stage prod

Each stage gets isolated resources and state.

CI/CD

For GitHub Actions or other CI:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: oven-sh/setup-bun@v1
      
      - run: bun install
      
      - run: bun run deploy --stage prod
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Required secrets:

ALCHEMY_PASSWORD - Encryption password for secrets
CLOUDFLARE_API_TOKEN - Cloudflare API token
Any other environment-specific secrets

See the Cloudflare with Alchemy guide for complete CI/CD setup.

Other deployment platforms

Better-T-Stack projects work with standard deployment platforms:

Vercel

Supported frameworks:

Next.js
TanStack Start
SvelteKit
Nuxt

Deploy:

Connect your Git repository to Vercel
Vercel auto-detects framework
Add environment variables in dashboard
Deploy

Configuration:

// vercel.json (if needed)
{
  "buildCommand": "bun run build",
  "outputDirectory": "dist",
  "installCommand": "bun install"
}

Netlify

Supported frameworks:

Next.js
SvelteKit
Nuxt
Astro

Deploy:

Connect repository to Netlify
Set build command: bun run build
Set publish directory (framework-specific)
Add environment variables
Deploy

Railway

Best for:

Backend APIs (Hono, Express, Fastify, Elysia)
Full-stack apps with databases

Deploy:

Create new project from GitHub repo
Railway auto-detects and deploys
Add environment variables
Database services available in dashboard

Render

Supported:

Web services (any framework)
Background workers
Databases (PostgreSQL, Redis)

Deploy:

Create new web service
Connect repository
Set build command and start command
Add environment variables
Deploy

Self-hosted (VPS, Docker)

Docker: Better-T-Stack projects can be containerized:

# Dockerfile (example for Hono server)
FROM oven/bun:latest

WORKDIR /app

COPY package.json bun.lock ./
COPY packages ./packages
COPY apps/server ./apps/server

RUN bun install --frozen-lockfile
RUN bun run build

EXPOSE 3000

CMD ["bun", "run", "apps/server/dist/index.js"]

Deploy:

docker build -t my-app .
docker run -p 3000:3000 --env-file .env my-app

Database deployment

Managed providers

For production databases, use managed providers: SQLite:

Turso (recommended for SQLite)
Cloudflare D1 (for Workers)

PostgreSQL:

Neon (serverless)
Supabase (with auth/storage)
Railway (simple deployment)
Render (free tier)

MySQL:

PlanetScale (serverless)
Railway
Render

MongoDB:

MongoDB Atlas (official)
Railway

See the Database setup guide for provider details.

Connection security

Use connection pooling: For serverless deployments, use connection pooling to avoid exhausting database connections:

// PostgreSQL with Neon
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);

Enable SSL: Always use SSL in production:

DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

Store credentials securely:

Use environment variables
Never commit .env files
Use secrets management (GitHub Secrets, Doppler, etc.)
For Alchemy, use alchemy.secret.env for automatic encryption

Environment variables

Production checklist

Database URLs

Update connection strings for production databases:

DATABASE_URL=postgresql://prod-user@prod-host/prod-db?sslmode=require

API URLs

Update frontend to point to production backend:

VITE_SERVER_URL=https://api.myapp.com

CORS origins

Configure backend to accept requests from production frontend:

CORS_ORIGIN=https://myapp.com

Auth secrets

Generate secure secrets for production:

BETTER_AUTH_SECRET=$(openssl rand -base64 32)
BETTER_AUTH_URL=https://api.myapp.com

Third-party keys

Use production API keys:

STRIPE_SECRET_KEY=sk_live_...
OPENAI_API_KEY=sk-...

Managing secrets

Option 1: Platform-specific

Vercel: Environment Variables in dashboard
Netlify: Site settings > Environment variables
Railway: Variables tab
Cloudflare: Alchemy encrypted secrets

Option 2: Secrets management service

Doppler - Centralized secrets management
Infisical - Open source secrets platform
AWS Secrets Manager
HashiCorp Vault

Post-deployment

Verify deployment

Test endpoints

curl https://your-app.workers.dev/health

Check database connection

Verify your app can connect to production database.

Test authentication

Monitor logs

Check platform logs for errors:

Cloudflare: Workers dashboard
Vercel: Deployment logs
Railway: Deployment logs

Monitoring

Add health checks:

// apps/server/src/index.ts
app.get("/health", (c) => {
  return c.json({ status: "ok", timestamp: Date.now() });
});

Log errors:

import { consola } from "consola";

app.onError((err, c) => {
  consola.error("Request error:", err);
  return c.json({ error: "Internal server error" }, 500);
});

Use APM tools:

Sentry - Error tracking
LogRocket - Session replay
Axiom - Serverless logging

Troubleshooting

Build fails

Common causes:

Missing dependencies in package.json
TypeScript errors
Environment variables not set

Solutions:

Run bun run build locally to reproduce
Check build logs for specific errors
Verify all dependencies are listed

Runtime errors

Common causes:

Missing environment variables
Database connection issues
CORS misconfiguration

Solutions:

Check platform logs
Verify all required env vars are set
Test database connection string locally
Verify CORS origins match exactly

Slow cold starts

Solutions:

Use Cloudflare Workers (V8 isolates, not containers)
Reduce bundle size
Use dynamic imports for large dependencies
Consider keeping functions warm with scheduled pings

Database connection pool exhausted

Solutions:

Use connection pooling (Neon, Supabase, PlanetScale all provide this)
Reduce max connections per function
Use serverless-friendly databases
Implement connection caching

Next steps

Cloudflare with Alchemy

Complete guide to Cloudflare Workers deployment

Database setup

Configure production databases

Project structure

Understand generated project layout

Troubleshooting

Common issues and solutions

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Overview

Cloudflare Workers deployment

What is Cloudflare Workers?

Enabling Cloudflare deployment

What you get

Deployment commands

Environment setup

Multi-stage deployments

CI/CD

Other deployment platforms

Vercel

Netlify

Railway

Render

Self-hosted (VPS, Docker)

Database deployment

Managed providers

Connection security

Environment variables

Production checklist

Managing secrets

Post-deployment

Verify deployment

Monitoring

Troubleshooting

Next steps

Cloudflare with Alchemy

Database setup

Project structure

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Documentation Index

​Overview

​Cloudflare Workers deployment

​What is Cloudflare Workers?

​Enabling Cloudflare deployment

​What you get

​Deployment commands

​Environment setup

​Multi-stage deployments

​CI/CD

​Other deployment platforms

​Vercel

​Netlify

​Railway

​Render

​Self-hosted (VPS, Docker)

​Database deployment

​Managed providers

​Connection security

​Environment variables

​Production checklist

​Managing secrets

​Post-deployment

​Verify deployment

​Monitoring

​Troubleshooting

​Next steps

Cloudflare with Alchemy

Database setup

Project structure

Troubleshooting

Build docs developers (and LLMs) love

Overview

Cloudflare Workers deployment

What is Cloudflare Workers?

Enabling Cloudflare deployment

What you get

Deployment commands

Environment setup

Multi-stage deployments

CI/CD

Other deployment platforms

Vercel

Netlify

Railway

Render

Self-hosted (VPS, Docker)

Database deployment

Managed providers

Connection security

Environment variables

Production checklist

Managing secrets

Post-deployment

Verify deployment

Monitoring

Troubleshooting

Next steps