alch-ts-hono Development Guide

This skill provides guidance for working with the Better-T-Stack monorepo featuring React 19, Hono, ORPC, and Better Auth.

Project Overview

A full-stack TypeScript monorepo with:

Development Workflow

Starting Development

1. **Start all services**: `bun dev` (web on :3001, server on :3000)

2. **Frontend only**: `bun dev:web`

3. **Backend only**: `bun dev:server`

4. **Build all**: `bun build`

Code Quality Checks

Database Operations

1. **Push schema changes**: `bun db:push`

2. **Open database UI**: `bun db:studio`

3. **Generate migrations**: `bun db:generate`

4. **Apply migrations**: `bun db:migrate`

⚠️ **Important**: Run `bun db:push` before first development session to initialize database schema.

Deployment

Monorepo Structure

```

apps/

├── web/ # Frontend React application

│ ├── src/

│ │ ├── routes/ # TanStack Router routes

│ │ ├── components/ # React components + shadcn/ui

│ │ ├── lib/ # Client utilities

│ │ └── utils/ # ORPC client setup

│ └── vite.config.ts

└── server/ # Backend Hono API

├── src/

│ ├── routers/ # ORPC router definitions

│ ├── db/ # Database schema + connection

│ │ └── schema/ # Drizzle schema files

│ ├── lib/ # Server utilities (auth, context, orpc)

│ └── index.ts # Main Hono app

├── drizzle.config.ts

└── wrangler.jsonc

```

Key Architectural Patterns

ORPC Type-Safe API

**Server-side routers** (`apps/server/src/routers/`):

**Client-side setup** (`apps/web/src/utils/orpc.ts`):

**Example procedure definition**:

```typescript

// apps/server/src/routers/example.ts

import { publicProcedure, protectedProcedure } from '../lib/orpc'

export const exampleRouter = {

getPublic: publicProcedure.input(z.object({...})).query(async (input, context) => {...}),

getProtected: protectedProcedure.query(async (input, context) => {...})

}

```

Authentication Flow

1. **Session management**: Better Auth handles sessions

2. **Context creation**: `apps/server/src/lib/context.ts` extracts session from requests

3. **Protection**: Use `protectedProcedure` for authenticated endpoints

4. **Session access**: Context includes `session` and `user` objects in protected procedures

Database Schema Management

1. **Schema location**: `apps/server/src/db/schema/` directory

2. **Connection**: Configured in `apps/server/src/db/index.ts`

3. **Workflow**: Define schema → `bun db:push` → access via Drizzle ORM

Code Conventions

Environment Configuration

Required environment variables in `apps/server/.env`:

1. **Database**: PostgreSQL connection string

2. **CORS**: Origin configuration for cross-origin requests

3. **Auth**: Better Auth secret and URL

Common Tasks

Adding a New API Endpoint

1. Create or update router in `apps/server/src/routers/`

2. Use `publicProcedure` or `protectedProcedure`

3. Define input schema with Zod

4. Implement query/mutation logic

5. Client automatically gets types via ORPC

Adding a New Database Table

1. Create schema file in `apps/server/src/db/schema/`

2. Define table using Drizzle syntax

3. Run `bun db:push` to apply changes

4. Access table via Drizzle ORM in procedures

Adding a New Frontend Route

1. Create route file in `apps/web/src/routes/`

2. Follow TanStack Router conventions

3. Use ORPC client from `apps/web/src/utils/orpc.ts`

4. Access type-safe API with full autocomplete

Adding shadcn/ui Components

1. Components located in `apps/web/src/components/`

2. Follow shadcn/ui installation patterns

3. Style with TailwindCSS utilities

Important Notes