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 and a Contract-First API design.

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.
API Design: Contract-First (OpenAPI). The frontend uses openapi-fetch with types generated from the backend's OpenAPI schema, ensuring a decoupled but type-safe connection.
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 (Syncs frontend types with backend 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 (Testing & Linting)

Backend Tests: bun run test (Runs Bun's native test runner for __tests__/api)
E2E Tests: bun run test:e2e (Runs Playwright browser tests for __tests__/e2e)
Lint: bun run lint (Biome check)
Format: bun run format (Biome write)
Type Check: bun x tsc --noEmit

Testing Architecture

The project uses two main categories for testing, consolidated in the __tests__/ directory:

API Testing (__tests__/api/): Uses Bun's native test runner. Covers unit tests for utilities, database integration, and Elysia API endpoint verification using api.handle().
E2E Testing (__tests__/e2e/): Uses Playwright. Covers end-to-end browser workflows like Login, Signup, and Dashboard interactions. Configured to run against the production build for maximum speed and accuracy.

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.
Routing: Use TanStack Router's file-based system in src/routes/.

API Workflow (Contract-First)

Backend First: Define schemas in Elysia routes (using t.Object, etc.).
Sync: Run bun run gen:api to export the OpenAPI schema.json and generate TypeScript types in generated/api.ts.
Frontend Usage: Use the apiClient from @/utils/api-client, which uses openapi-fetch for type-safe requests.

Backend/API

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

Frontend

Theme: Mantine is configured via MantineProvider in src/frontend.tsx.
Modals: Use the imperative modals manager from @mantine/modals.
State Management: Valtio is used for simple proxy-based state (see src/store/).

Project Layout

src/index.ts: Unified server entry point (Dev/Prod conditional logic).
src/vite.ts: Vite server configuration (Dev-only).
src/api/: Elysia route modules and schema definitions.
src/routes/: Frontend route definitions and layouts.
src/utils/: Shared utilities (Auth, DB, Env, API Client).
scripts/: Automation scripts (e.g., generate-schema.ts).
generated/: Auto-generated artifacts (OpenAPI schema and types).
__tests__/: Centralized testing directory (api/ and e2e/).
prisma/: Database schema and migrations.
dist/: Production build output.

4.6 KiB Raw Blame History