Hono Server + CockroachDB + NextAuth.js + Prisma ORM Edge Native Stack - CLAUDE.md Template

Overview

The CLAUDE.md template for Hono Server + CockroachDB + NextAuth.js + Prisma ORM Edge Native Stack provides engineers with a ready-to-copy Claude Code blueprint to scaffold a secure, low-latency edge-native application. It covers authentication via NextAuth.js, data modeling and access via Prisma ORM optimized for edge runtimes, and a resilient CockroachDB-backed data layer.

When to Use This CLAUDE.md Template

• Building an edge-native API using Hono as the request router and runtime
• Implementing authentication via NextAuth.js with Prisma adapters
• Connecting to CockroachDB with a Prisma schema tuned for edge workloads
• Deploying to edge providers (Cloudflare, Vercel Edge, Bun-based runtimes)

Copyable CLAUDE.md Template

# CLAUDE.md

role: You are Claude, a software engineering assistant focused on producing production-grade, edge-native stacks using Hono, CockroachDB, NextAuth.js, and Prisma ORM for the Edge Native runtime.

architecture:
  - Edge-native runtime (Hono) for low-latency HTTP routing
  - CockroachDB as a globally distributed database with TLS and per-tenant security
  - Prisma ORM in Edge Native mode for fast data access
  - NextAuth.js as the authentication layer, with Prisma adapter
  - Layered architecture: edge router & api handlers & data access

fileStructure:
  - apps/edge/
  - prisma/schema.prisma
  - apps/edge/src/
  - apps/edge/src/routes.ts
  - apps/edge/src/middleware.ts
  - apps/edge/package.json
  - .env

authentication:
  - Use NextAuth.js with a Prisma adapter
  - Sessions stored in httpOnly cookies with sameSite=lax if appropriate
  - Enforce JWT or database-backed sessions as needed by deployment

database:
  - CockroachDB cluster accessible via TLS
  - Prisma schema models reflecting multi-tenant access
  - Connection string from environment variables

validation:
  - All inputs validated with schema validation before DB access
  - Use Zod/Yup schemas on edge handlers

security:
  - Do not hard-code secrets
  - Do not expose DB credentials on the client
  - Do not bypass TLS for DB connections
  - Do not disable CSRF on state-changing requests

testing:
  - Unit tests for edge handlers
  - Integration tests for NextAuth.js flows
  - End-to-end tests against a local CockroachDB cluster

deployment:
  - Deploy to an Edge-native target (Vercel Edge, Cloudflare Workers, Bun-based runtimes)
  - Use environment-specific config (DEV/PROD) via environment variables

things Claude must not do:
  - Do not use non-edge-safe libs in route handlers
  - Do not bypass TTL checks on sessions
  - Do not connect to CockroachDB without TLS
  - Do not store plaintext credentials
  - Do not generate secrets at runtime in code

Recommended Project Structure

├─ apps/
│  └─ edge/
│     ├─ src/
│     │  ├─ main.ts           # Hono app bootstrap
│     │  ├─ routes.ts         # Edge API routes
│     │  └─ middleware.ts     # Global middleware
│     ├─ package.json
│     └─ tsconfig.json
├─ prisma/
│  └─ schema.prisma
├─ .env
├─ nextauth.config.ts         # NextAuth.js config with Prisma adapter
├─ README.md

Core Engineering Principles

• Keep latency low by keeping logic close to the edge and minimizing DB round-trips
• Favor type safety across edge handlers with Prisma schemas and TZ-safe date handling
• Use a single source of truth for sessions and user state via NextAuth.js
• Isolate data access with a clean repository layer and Prisma client per request
• Operate under a secure by-default posture (secrets, TLS, CSRF, and least privilege)

Code Construction Rules

• Use the exact Hono + CockroachDB + NextAuth.js + Prisma setup in code blocks
• Do not import non-edge-safe libraries into edge handlers
• Do not bypass TLS when connecting to CockroachDB
• Do not expose private keys or DB credentials in the client bundle
• Do not hard-code credentials or secrets in source code
• Keep Prisma in Edge Native mode and avoid server-side-only features

Security and Production Rules

• Store secrets in environment variables or a secret manager
• Use TLS for CockroachDB connections
• Enable CSRF protection for state-changing requests
• Configure secure cookies (HttpOnly, Secure, SameSite)
• Implement rate limiting at the edge where feasible

Testing Checklist

• Unit tests for edge handlers and Prisma data access layer
• Integration tests for NextAuth.js login/logout flows
• End-to-end tests against a local CockroachDB cluster
• Contract tests for API contracts between edge routes and data layer

Common Mistakes to Avoid

• Overloading edge handlers with heavy computation
• Disabling TLS or ignoring secret management best practices
• Using non-edge-safe libraries in the edge runtime
• Assuming multi-tenant isolation is implicit without proper tenant checks

FAQ

• What is the purpose of this CLAUDE.md Template?

  To provide a copyable Claude Code blueprint for building an edge-native stack with Hono, CockroachDB, NextAuth.js, and Prisma ORM.

• Which environments does this template target?

  Edge runtimes (Vercel Edge, Cloudflare Workers, Bun-based edges) with TLS-backed CockroachDB connections.

• Can I customize the Prisma schema for multi-tenant data?

  Yes. The template includes tenant-aware models and per-request Prisma clients.

• Does this template include NextAuth.js configuration?

  Yes, with a Prisma adapter and edge-safe session management.

• Where are secrets stored?

  In environment variables or a secret manager; never in code.