⚡ 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