GEMINI.md

This project is makuro-base-template, a high-performance, full-stack React development template leveraging the Bun runtime. It is designed for a seamless developer experience with a unified "single-port" architecture.

Project Overview

Runtime: Bun
Architecture: "Single Port" (default: 3000). ElysiaJS serves as the main HTTP server, integrating Vite in middleware mode during development to provide HMR and React Dev Inspector support.
Frontend: React 19 with TanStack React Router for type-safe, file-based routing.
UI Framework: Mantine UI for a comprehensive component library and hooks.
Authentication: Better Auth integrated with Elysia.
Database: Prisma ORM for type-safe database access.
Tooling: Biome for ultra-fast linting and formatting.

Building and Running

Development

Install dependencies: bun install
Start development server: bun run dev (Runs Elysia + Vite Middleware)
Update Route Tree: bun x tsr generate (usually automatic via Vite plugin)
Generate API Types: bun run gen:api (Generates types from OpenAPI schema)
Database Migration: bun x prisma migrate dev

Production

Build Frontend: bun run build (Outputs to dist/)
Start Production Server: bun run start (Serves pre-built assets from dist/ via Elysia)

Quality Control

Lint: bun run lint (Biome check)
Format: bun run format (Biome write)
Type Check: bun x tsc --noEmit

Development Conventions

Code Style & Structure

Formatting: Strictly use Biome. The project uses tab indentation and double quotes for JavaScript/TypeScript.
Imports:
- Use the node: protocol for Node.js built-ins (e.g., import fs from "node:fs").
- Use the @/ alias for absolute paths from the src/ directory (e.g., import { auth } from "@/utils/auth").
Routing: New routes should be added as files in src/routes/ to leverage TanStack Router's file-based routing system.

Backend/API

Prefix: All backend API routes are prefixed with /api.
Documentation: Swagger documentation is available at /api/docs in development.
Authentication: Handled at /api/auth/*. Protected routes use the apiMiddleware and custom guards.

Frontend

Theme: Mantine is configured via MantineProvider in src/App.tsx.
State Management: Valtio is used for simple proxy-based state (see src/store/).
Dev Tools: TanStack Router Devtools and React Dev Inspector are enabled in development.

Project Layout

src/index.ts: Unified server entry point (Dev/Prod conditional logic).
src/vite.ts: Vite server configuration (Dev-only).
src/routes/: Frontend route definitions and layouts.
src/api/: Elysia route modules.
src/utils/: Shared utilities (Auth, DB, Logging).
prisma/: Database schema and migrations.
dist/: Production build output (Git ignored).

3.2 KiB Raw Blame History