create-ely 0.1.1

package/templates/monorepo/apps/backend/CHANGELOG.md

@@ -0,0 +1,190 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.5] - 2026-01-03
+
+### Changed
+
+- Updated dependencies to the latest version
+
+## [0.4.4] - 2025-12-25
+
+### Added
+
+- Added `CLAUDE.md` with comprehensive development guidelines for AI-assisted development
+- Added `ENABLE_OPENAPI` environment variable to control OpenAPI documentation availability
+- Added new `src/middleware/error-handler.ts` for centralized error handling
+- Added startup logging to indicate OpenAPI documentation availability status
+
+### Changed
+
+- Extracted global error handler into separate middleware file (`src/middleware/error-handler.ts`)
+- Enhanced error logging in users module to log all caught errors before returning responses
+- Updated `src/common/logger.ts` to use raw `pino` instead of elysia-logger wrapper
+- Updated OpenAPI integration to respect `ENABLE_OPENAPI` configuration
+- Updated `.env.example` with `ENABLE_OPENAPI` setting and changed default `LOG_LEVEL` to `debug`
+- Updated dependencies: `@elysiajs/openapi` to ^1.4.12, `drizzle-orm` to ^0.45.1, `elysia` to ^1.4.19
+- Cleaned up `src/main.ts` by moving error handling logic to dedicated middleware
+
+### Removed
+
+- Removed `@bogeychan/elysia-logger` dependency in favor of raw Pino integration
+
+## [0.4.3] - 2025-12-15
+
+### Changed
+
+- Improved `README.md` with up-to-date docs
+- Fixed database variable value in `.env.example` to work with `docker-compose.yml` deployment out of the box
+- Updated Elysia to the latest `1.4.19` version
+
+## [0.4.2] - 2025-12-06
+
+### Added
+
+- Added database migration error handling
+- Added automatic database migrations on server startup
+
+### Changed
+
+- Updated dependencies to the latest version
+- Changed the way server starts to be more robust
+
+## [0.4.1] - 2025-12-03
+
+### Changed
+
+- Updated dependencies to the latest version
+- Updated error handling to be more robust
+- Updated ci workflows to use action environment variables instead of test environment
+
+### Fixed
+
+- Fixed error logging to not expose sensitive request information
+
+## [0.3.1] - 2025-12-01
+
+### Changed
+
+- Updated graceful shutdown functionality to be more robust
+- Updated dependencies to the latest version
+
+### Added
+
+- Added `@types/pg` to dev dependencies for type safety
+
+## [0.3.0] - 2025-11-27
+
+### Changed
+
+- Updated logger integration to use plugin-based approach at root app level
+- Improved app initialization and launch process with proper signal handling (SIGINT/SIGTERM)
+- Enhanced error logging with structured HTTP request context
+- Improved error handling in the users module
+
+## [0.2.4] - 2025-11-20
+
+### Fixed
+
+- Fixed `README.md` to use correct workflow name
+
+## [0.2.2] - 2025-11-20
+
+### Fixed
+
+- Fixed workflows to use environment variables
+
+## [0.2.0] - 2025-11-20
+
+### Added
+
+- Added local MCP server configuration
+- Added CI lint workflow
+- Added Biome-based formatting/linting
+- Added VS Code recommendations/settings included
+- Added project guidelines and updated changelog
+
+### Fixed
+
+- Improved user-creation error handling with clearer 422 responses and more robust failure checks
+
+### Changed
+
+- Updated dependencies to the latest version
+- Updated tests for consistent formatting and interaction patterns
+
+## [0.1.6] - 2025-11-11
+
+### Changed
+
+- Dependencies updated to the latest version
+- Fixed the way we define models
+- Moved database-related files to `src/db`
+- Moved common files to `src/common`
+- Removed aliases from `tsconfig.json` as it may interfere with monorepo setups
+
+### Added
+
+- Added `timestamp` prefix to migrations
+
+## [0.1.5] - 2025-09-30
+
+### Changed
+
+- Updated dependencies to the latest version
+- Updated the way we use logger
+- Improved `openapi` documentation
+
+## [0.1.4] - 2025-09-16
+
+### Changed
+
+- Updated packages to the latest version
+- Improved `Dockerfile`
+
+## [0.1.2] - 2025-09-14
+
+### Added
+
+- Added test directory to `bunfig.toml`
+- Added users test file
+
+### Fixed
+
+- Fixed `LOG_LEVEL` type in `config.ts`
+- Fixed mistaken comment in `users/index.ts`
+
+### Changed
+
+- Updated `README.md` with testing information and some badges
+
+## [0.1.1] - 2025-09-14
+
+### Changed
+
+- Removed invalid parameters from `bunfig.toml` and disabled telemetry
+
+## [0.1.0] - 2025-09-14
+
+### Added
+
+- Elysia web framework with TypeScript and Bun runtime
+- PostgreSQL database with Drizzle ORM
+- User management API endpoints
+- OpenAPI documentation generation
+- Docker and Docker Compose configuration
+- Database migration system
+- Pino logger with development pretty printing
+- Environment variable validation with Envalid
+- Hot reload development server
+- Initial users table schema
+
+### Changed
+
+- Updated OpenAPI documentation URLs from `/swagger` to `/openapi`

package/templates/monorepo/apps/backend/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+```bash
+# Dependencies
+bun install                    # Install dependencies
+
+# Development
+bun run dev                    # Start dev server with hot reload
+bun run start                  # Start production server
+bun run build                  # Build optimized binary
+
+# Database (Drizzle ORM)
+bun run db:generate            # Generate migration after schema changes
+bun run db:migrate             # Apply pending migrations
+bun run db:studio              # Open Drizzle Studio GUI
+
+# Code Quality
+bun run lint                   # Check for lint errors
+bun run lint:fix               # Auto-fix lint issues
+bun run format                 # Format code with Biome
+
+# Testing
+bun test                       # Run all tests
+bun test --coverage            # Run tests with coverage report
+
+# Docker
+docker-compose up -d           # Start all services (app + postgres)
+docker-compose up -d elysia-boilerplate-postgres  # PostgreSQL only
+docker-compose logs -f         # View logs
+docker-compose down            # Stop all services
+```
+
+## Architecture Overview
+
+### Request Flow
+1. Request enters through `src/main.ts` (root Elysia app)
+2. Global middleware applied: CORS, error handling, OpenAPI
+3. Routed to module in `src/modules/` (e.g., `/users` → `src/modules/users/`)
+4. Module structure: `index.ts` (routes) → `service.ts` (business logic) → database
+
+### Logger Architecture (CRITICAL)
+The logger is initialized **once** in `src/main.ts` using `.use(log.into({...}))`. To avoid duplicate logs:
+- **DO NOT** use logger from Elysia context (`ctx.log`) in submodules
+- **ALWAYS** import logger directly: `import { log } from 'src/common/logger'`
+- Create child loggers for modules: `const log = logger.child({ name: 'module-name' })`
+
+Example from `src/modules/users/index.ts`:
+```typescript
+import { log as logger } from 'src/common/logger';
+const log = logger.child({ name: 'users' });
+```
+
+### Module Pattern
+Each module in `src/modules/` follows this structure:
+
+1. **`schema/` in `src/db/schema/`**: Drizzle table definition + validation schemas
+   - Define table with `pgTable()`
+   - Export `createInsertSchema`, `createSelectSchema`, `createUpdateSchema` from drizzle-typebox
+   - Add Elysia field refinements (validation rules)
+
+2. **`model.ts`**: Type definitions and Elysia model plugin
+   - Define request/response types using Elysia's `t` (TypeBox)
+   - Create namespace (e.g., `UsersModel`) with typed DTOs
+   - Export Elysia plugin with `.model()` to register schemas
+
+3. **`service.ts`**: Business logic and database operations
+   - Pure functions that interact with database
+   - No HTTP concerns (status codes, headers, etc.)
+
+4. **`index.ts`**: Route definitions (Elysia controller)
+   - Define routes with `.get()`, `.post()`, etc.
+   - Reference models by string: `body: 'users.createRequest'`
+   - Handle errors and return proper HTTP status codes
+   - OpenAPI documentation in `detail` field
+
+### Database Schema Pattern
+When creating/modifying tables in `src/db/schema/`:
+
+```typescript
+// 1. Define table
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().$defaultFn(() => Bun.randomUUIDv7()),
+  // ... fields
+});
+
+// 2. Define validation refinements for Elysia
+const fieldRefinements = {
+  name: t.String({ minLength: 1, maxLength: 255 }),
+};
+
+// 3. Create schemas (avoid infinite type instantiation)
+const _userCreate = createInsertSchema(users, fieldRefinements);
+const _userSelect = createSelectSchema(users, fieldRefinements);
+const _userUpdate = createUpdateSchema(users, fieldRefinements);
+
+// 4. Export with explicit types
+export const userCreate = _userCreate;
+export const userSelect = _userSelect;
+export const userUpdate = _userUpdate;
+```
+
+After schema changes, run `bun run db:generate` to create migration.
+
+### Environment Configuration
+- All env vars validated in `src/common/config.ts` using Envalid
+- **NEVER** use `process.env` or `Bun.env` directly in application code
+- Always import: `import config from 'src/common/config'`
+- Available config: `NODE_ENV`, `LOG_LEVEL`, `SERVER_HOSTNAME`, `SERVER_PORT`, `DATABASE_URL`, `DB_AUTO_MIGRATE`, `ENABLE_OPENAPI`
+
+### Error Handling
+Global error handler in `src/middleware/error-handler.ts`:
+- Elysia's handled errors (status codes) pass through
+- Unhandled errors are logged with context (method, URL, referrer)
+- Clients receive generic "Internal Server Error" (never expose details)
+
+### Bootstrap Process
+`src/main.ts` bootstrap function:
+1. Run database migrations (if `DB_AUTO_MIGRATE=true`)
+2. Start HTTP server
+3. Register graceful shutdown handlers (SIGINT, SIGTERM)
+
+If bootstrap fails, app logs fatal error and exits with code 1.
+
+## Branch Strategy
+- `main`: Production releases
+- `develop`: Integration branch (default PR target)
+- `feature/*`: New features
+- GitHub Actions run lint checks on push/PR to `main` and `develop`
+
+## TypeScript Configuration
+- Strict mode enabled (`strict: true`)
+- No unchecked indexed access (`noUncheckedIndexedAccess: true`)
+- Module resolution: `bundler` (Bun-specific)
+- Base URL set to `.` for absolute imports from project root
+
+## Testing
+- Test files in `src/tests/` named `*.test.ts`
+- Use Bun's built-in test runner
+- All new features require tests
+
+## Code Style
+- Linter: Biome (config in `biome.json`)
+- Run `bun run lint:fix` before committing
+- No `any` types unless absolutely necessary
+- Use explicit imports (no `import *`)

package/templates/monorepo/apps/backend/Dockerfile

@@ -0,0 +1,35 @@
+# Build stage
+FROM oven/bun:1.3.2-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lock ./
+
+# Install dependencies
+RUN bun install
+
+# Copy source files
+COPY src ./src
+COPY drizzle.config.ts ./
+COPY tsconfig.json ./
+
+# Build the application for Linux
+RUN bun build --compile --minify-whitespace --minify-syntax --outfile build/server src/main.ts
+
+# Final stage - ultra-minimal runtime using alpine-glibc (16MB base)
+FROM frolvlad/alpine-glibc
+
+# Install only essential C++ runtime libraries (minimal overhead)
+RUN apk --no-cache add libstdc++ libgcc
+
+# Copy the compiled binary directly from builder stage
+COPY --from=builder /app/build/server /server
+
+# Make the binary executable
+RUN chmod +x /server
+
+EXPOSE 3000
+
+# Use the compressed binary
+CMD ["/server"]

package/templates/monorepo/apps/backend/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Elysia Boilerplate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/monorepo/apps/backend/README.md

@@ -0,0 +1,274 @@
+# Elysia Boilerplate
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/Bun-000?logo=bun&logoColor=fff)](https://bun.sh)
+[![Postgres](https://img.shields.io/badge/Postgres-%23316192.svg?logo=postgresql&logoColor=white)](https://www.postgresql.org)
+[![Drizzle](https://img.shields.io/badge/Drizzle-C5F74F?logo=drizzle&logoColor=000)](https://orm.drizzle.team)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://www.docker.com)
+[![Tests](https://github.com/truehazker/elysia-boilerplate/actions/workflows/tests.yml/badge.svg)](https://github.com/truehazker/elysia-boilerplate/actions/workflows/tests.yml)
+[![Lint](https://github.com/truehazker/elysia-boilerplate/actions/workflows/lint.yml/badge.svg)](https://github.com/truehazker/elysia-boilerplate/actions/workflows/lint.yml)
+
+A modern, production-ready boilerplate for building APIs with Elysia, Bun runtime, and PostgreSQL.
+
+## Features
+
+- **Elysia** - Fast and ergonomic web framework
+- **Bun** - Ultra-fast JavaScript runtime and package manager
+- **PostgreSQL** - Robust relational database
+- **Drizzle ORM** - Type-safe SQL ORM with excellent TypeScript support
+- **Pino Logger** - High-performance JSON logger
+- **OpenAPI** - Automatic API documentation generation
+- **Environment Configuration** - Type-safe environment variable validation with Envalid
+- **Modular Architecture** - Clean, organized code structure
+
+## Prerequisites
+
+- [Bun](https://bun.sh) (latest version)
+
+## Installation
+
+1. **Clone the repository**
+
+   ```bash
+   git clone <repository-url>
+   cd elysia-boilerplate
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   bun install
+   ```
+
+3. **Set up PostgreSQL**
+
+   **Recommended approach**: The easiest way to get started is to use the provided Docker Compose setup, which will start PostgreSQL instantly:
+
+   ```bash
+   docker-compose up -d elysia-boilerplate-postgres
+   ```
+
+   **Alternative**: If you prefer to run your own PostgreSQL instance, create a database for your project and note the connection details (host, port, database name, username, password). **Remember to update your `.env` file** with the correct `DATABASE_URL` connection string.
+
+4. **Create and configure environment variables**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   **Important**: You must create a `.env` file from the provided `.env.example` template and update it with your PostgreSQL connection details:
+
+   ```env
+   NODE_ENV=development
+   LOG_LEVEL=info
+   SERVER_HOSTNAME=localhost
+   SERVER_PORT=3000
+   DATABASE_URL=postgresql://username:password@localhost:5432/your_database_name
+   ```
+
+5. **Run database migrations**
+
+   ```bash
+   bun run db:migrate
+   ```
+
+## Development
+
+Start the development server with hot reload:
+
+```bash
+bun run dev
+```
+
+The server will start at `http://localhost:3000` (or your configured port).
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun run dev` | Start development server with hot reload |
+| `bun run start` | Start production server |
+| `bun run build` | Build the application for production |
+| `bun run db:generate` | Generate a new database migration |
+| `bun run db:migrate` | Apply pending migrations to the database |
+| `bun run db:studio` | Open Drizzle Studio for database management |
+| `docker-compose up -d` | Start the entire stack with Docker Compose |
+| `docker-compose down` | Stop all Docker services |
+| `docker-compose logs -f` | View logs from all services |
+
+## Testing
+
+This project includes a testing setup using Bun's built-in test runner. Tests are located in the `src/tests/` folder.
+
+### Running Tests
+
+To run all tests:
+
+```bash
+bun test
+```
+
+To run tests with coverage:
+
+```bash
+bun test --coverage
+```
+
+### Adding Tests
+
+Add your test files to the `src/tests/` folder. Test files should follow the naming convention `*.test.ts`.
+
+Example test structure:
+
+```text
+src/tests/
+├── users.test.ts         # User module tests
+├── auth.test.ts          # Authentication tests
+└── api.test.ts           # API endpoint tests
+```
+
+## Project Structure
+
+```text
+src/
+├── db/                   # Database configuration and schema
+│   ├── migrations/       # Database migrations
+│   ├── index.ts          # Database connection setup
+│   └── schema/           # Drizzle schema definitions
+├── common/               # Shared utilities
+│   ├── config.ts         # Environment configuration
+│   └── logger.ts         # Logger setup
+├── modules/              # Feature modules
+│   └── users/            # User module example
+│       ├── index.ts      # Route definitions
+│       ├── model.ts      # Data models
+│       └── service.ts    # Business logic
+└── main.ts               # Application entry point
+```
+
+### Important Notes on Logger Usage
+
+The logger is initialized in the root application (`src/main.ts`) using `.use(log.into({...}))`. To avoid duplicate logs, submodules should import and use the logger directly from `src/common/logger` rather than relying on Elysia's context. Using the logger from context in submodules will result in duplicate log entries.
+
+**Example:**
+
+```typescript
+// ✅ Correct: Import logger directly
+import { log } from 'src/common/logger';
+
+// ❌ Incorrect: Using logger from Elysia context in submodules
+// This will cause duplicate logs
+```
+
+## Configuration
+
+The application uses [Envalid](https://github.com/af/envalid) for type-safe environment variable validation. All configuration is centralized in `src/common/config.ts`.
+
+### Environment Variables
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `NODE_ENV` | string | `development` | Application environment |
+| `LOG_LEVEL` | string | `info` | Logging level |
+| `SERVER_HOSTNAME` | string | `localhost` | Server hostname |
+| `SERVER_PORT` | number | `3000` | Server port |
+| `DATABASE_URL` | string | `postgresql://postgres:postgres@localhost:5432/elysia-boilerplate` | PostgreSQL connection URL |
+
+## API Documentation
+
+Once the server is running, you can access the interactive API documentation at:
+
+- **Scala UI**: `http://localhost:3000/openapi`
+- **OpenAPI JSON**: `http://localhost:3000/openapi/json`
+
+## Database Management
+
+### Generate a new migration
+
+```bash
+bun run db:generate
+```
+
+### Apply migrations
+
+```bash
+bun run db:migrate
+```
+
+### Open Drizzle Studio
+
+```bash
+bun run db:studio
+```
+
+## Docker Deployment
+
+This project includes Docker configuration for easy deployment and development.
+
+### Using Docker Compose (Recommended)
+
+The easiest way to run the entire stack is with Docker Compose:
+
+```bash
+# Start all services (app + database)
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop all services
+docker-compose down
+```
+
+This will start:
+
+- **Elysia application** on `http://localhost:3000`
+- **PostgreSQL database** on `localhost:5432`
+- **Automatic database migrations** on startup
+
+### Docker Configuration
+
+- **Dockerfile**: Multi-stage build using Bun runtime, compiles TypeScript and creates optimized binary
+- **docker-compose.yml**: Complete stack with PostgreSQL, health checks, and persistent data storage
+- **Environment**: Production-ready configuration with proper networking and restart policies
+
+## Production Deployment
+
+1. **Build the application**
+
+   ```bash
+   bun run build
+   ```
+
+2. **Set production environment variables**
+
+   ```bash
+   export NODE_ENV=production
+   export DATABASE_URL=your_production_database_url
+   # ... other production variables
+   ```
+
+3. **Run the application**
+
+   ```bash
+   ./build/server
+   ```
+
+## Using Agents
+
+This repository features an `AGENTS.md` file that outlines the recommended tools and commands for using agents.
+
+You can use cursor, claude, etc. to use agents
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.