SST Run

A minimal full-stack starter for Bun, React, Hono, Better Auth, Drizzle, PostgreSQL, and SST.

Create A Project

npx create-sst-run my-app

If you omit my-app, the CLI prompts for the project name.

When published under the create-sst-run package name, this also works with:

npm create sst-run@latest my-app

The create script copies the starter into a new directory, rewrites the generated root package name, and can optionally run bun install and git init.

Stack

• Bun workspaces for package management and scripts
• React 19, Vite, TanStack Router, TanStack Query, Tailwind CSS v4, and shadcn/ui source components in apps/web
• Hono, Better Auth, Drizzle ORM, and PostgreSQL in apps/api
• Shared Zod contracts in packages/shared
• Runtime environment validation in packages/config
• SST for AWS deployment with same-origin /api routing

Workspace Layout

apps/
  api/        Hono API, auth, feature modules, Drizzle schema
  web/        React app, routes, API client, UI components
packages/
  config/     Environment validation
  shared/     Shared Zod contracts and types

The API keeps feature behavior under apps/api/modules/<feature>. The starter includes a small example module that shows the route/service/shared-contract pattern.

Development

Install dependencies:

bun install

Create local env files:

cp apps/api/.env.example apps/api/.env.local
cp apps/web/.env.example apps/web/.env.local

Fill in the API values in apps/api/.env.local, then run:

bun run dev

Local ports default to:

• Web: 3000
• API: 6769
• Drizzle Studio: 4984

Useful commands:

bun run type-check
bun run lint
bun run build
bun run --cwd apps/api test:unit

Environment

apps/api/.env.local is validated by packages/config/env.ts.

Required API values:

• DATABASE_URL
• BETTER_AUTH_SECRET

Optional API values:

• DATABASE_URL_UNPOOLED for Drizzle Kit migrations
• AUTH_CANONICAL_ORIGIN for deployed preview OAuth flows
• AUTH_ALLOWED_HOST, set by SST for deployed auth host validation
• OAUTH_PROXY_SECRET, defaults to BETTER_AUTH_SECRET if omitted
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for Google sign-in
• GOOGLE_ALLOWED_DOMAIN to restrict Google sign-in to one Workspace domain

Web env values are optional and currently only control local ports.

Database

The schema lives in apps/api/db/schema.ts. The starter keeps the Better Auth tables and exports a baseColumns helper for application-owned tables.

Generate and run migrations after changing the schema:

bun run db:generate
bun run db:migrate

Use db:push only for disposable local databases.

Authentication

Better Auth is mounted under /api/auth. The browser talks to auth and API routes through the same origin:

• Local Vite proxies /api to the API dev server.
• Deployed SST routes /api/* to the API service.

Google sign-in is enabled when GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set. For local development with the default web port, configure Google OAuth with:

• Authorized JavaScript origin: http://localhost:3000
• Authorized redirect URI: http://localhost:3000/api/auth/callback/google

Deployment

SST configuration lives in sst.config.ts. Production and preview stages read secrets from AWS Secrets Manager:

• Production default: prod/sst-run
• Preview default: preview/sst-run/<stage>

Set SST_RUN_SECRET_NAME to override the production secret name.

Deploy with:

bunx sst deploy --stage production