⚡ bhaze

Bun · Hono · Arc · Zod · Ecosystem

A production-ready API starter with RFC 7807 error handling, type-safe env validation, and zero process.env leaks.

---

Quick Start

npx create-bhaze my-api
cd my-api
bun install
bun run dev

Server starts at http://localhost:5085.

---

What You Get

Feature	Details
Runtime	Bun (primary) + Node.js (fallback)
Framework	Hono with middleware stack
ORM	Prisma + PostgreSQL
Validation	Zod for env + request bodies
Errors	RFC 7807 Problem Details
Security	CORS, CSRF, rate limiting, secure headers, timeout
TypeScript	Full strict mode, path aliases

---

Project Structure

src/
├── config/env.ts            # Env validation (Zod) — the ONLY process.env
├── controllers/             # Request handlers (wrap in withHandler)
├── lib/
│   ├── app-error.ts         # RFC 7807 AppError class
│   ├── db.ts                # Prisma singleton
│   ├── helper.ts            # withHandler() wrapper
│   ├── response.ts          # sendSuccess / sendError
│   └── validator.ts         # Zod validator with RFC 7807 errors
├── routes/                  # Hono routers
├── services/                # Business logic (throws AppError)
├── types/                   # Public type exports
└── validators/              # Zod schemas

---

Response Format

Success

{
  "success": true,
  "message": "User fetched successfully",
  "data": { "id": "abc-123", "name": "John" }
}

Error (RFC 7807)

{
  "type": "https://api.bhaze.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "User not found",
  "instance": "/api/users/abc123"
}

---

Error Handling

import { AppError } from "@lib/app-error";

throw AppError.notFound("User");
throw AppError.conflict("Email already exists");
throw AppError.badRequest("Validation failed", { fields: { email: "Invalid" } });

---

Environment Variables

All env vars validated at startup via Zod. Never use process.env directly.

import env from "@config/env";
const port = env.PORT; // ✅ typed, validated

Variable	Default	Description
PORT	5085	Server port
NODE_ENV	development	Runtime environment
DATABASE_URL	postgresql://...	PostgreSQL connection
ALLOWED_ORIGINS	http://localhost:5085,...	CORS origins
RATE_LIMIT_MAX	120	Max requests per window
TIMEOUT_MS	30000	Request timeout

---

Scripts

Command	Description
bun run dev	Dev server with hot reload
npm run dev:node	Dev server (Node.js)
bun run start	Production server
bun run db:generate	Generate Prisma client
bun run db:migrate	Run migrations
bun run db:push	Push schema to DB
bun run typecheck	TypeScript check
bun run format	Format with Prettier

---

Adding a Resource

1. src/validators/product.validator.ts — Zod schema
2. src/services/product.service.ts — Business logic
3. src/controllers/product.controller.ts — HTTP handlers
4. src/routes/product.routes.ts — Wire routes
5. src/routes/index.ts — Register

---

License

MIT