68 lines
3.8 KiB
Markdown
68 lines
3.8 KiB
Markdown
# 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](https://bun.sh/)
|
|
* **Architecture**: "Single Port" (default: 3000). [ElysiaJS](https://elysiajs.com/) serves as the main HTTP server, integrating [Vite](https://vitejs.dev/) 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](https://tanstack.com/router/latest) for type-safe, file-based routing.
|
|
* **UI Framework**: [Mantine UI](https://mantine.dev/) for a comprehensive component library and hooks.
|
|
* **Authentication**: [Better Auth](https://www.better-auth.com/) integrated with Elysia.
|
|
* **Database**: [Prisma ORM](https://www.prisma.io/) for type-safe database access.
|
|
* **Tooling**: [Biome](https://biomejs.dev/) 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
|
|
* **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.
|
|
* **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](https://valtio.pmnd.rs/) 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).
|
|
* `prisma/`: Database schema and migrations.
|
|
* `dist/`: Production build output. |