A modern, interactive tier list maker built with React, TypeScript, and Clean Architecture principles. Create and customize tier lists with drag-and-drop functionality, image uploads, and real-time editing.
- 🎯 Drag & Drop Interface - Intuitive tier list creation with smooth interactions
- 📸 Image Upload - Support for JPEG, PNG, GIF, and WebP formats
- 🎨 Customizable Tiers - Color-coded tiers with editable labels
- 💾 Auto-save - Real-time persistence with external database
- 📱 Responsive Design - Works seamlessly on desktop and mobile
- 🔧 Clean Architecture - Maintainable codebase with separation of concerns
- 🚀 Modern Stack - Built with React 19, TypeScript, Bun, and TailwindCSS
This project follows Clean Architecture principles with clear separation between:
- Core Layer - Business entities and use cases
- Infrastructure Layer - Database and storage implementations
- Presentation Layer - React components and UI
- Features Layer - Domain-specific functionality
- Shared Layer - Reusable utilities and components
- Bun (latest version)
- Docker & Docker Compose (for containerized setup)
- Database provider (PostgreSQL-compatible)
- S3-compatible storage provider (Vultr, AWS S3, etc.) or local MinIO
-
Clone the repository
git clone <repository-url> cd tierlist-builder
-
Install dependencies
bun install
-
Configure environment
cp .env.example .env # Edit .env with your configuration -
Start development server
bun run dev
-
Open your browser
http://localhost:3000
For a complete development environment with local services:
# Start app with local S3-compatible storage
docker-compose --profile local-storage up
# Start app with caching
docker-compose --profile local-storage --profile cache up
# Access MinIO Console at http://localhost:9001
# Access app at http://localhost:3000Copy .env.example to .env and configure the following:
# Database (PostgreSQL-compatible)
DATABASE_URL=https://your-project-id.example.co
DATABASE_ANON_KEY=your-database-anon-key
# Object Storage (Vultr, AWS S3, DigitalOcean Spaces, etc.)
S3_ENDPOINT=https://ewr1.vultrobjects.com
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_BUCKET_NAME=tierlist-images
S3_REGION=us-east-1# Application settings
APP_NAME="Your Tierlist App"
MAX_IMAGE_SIZE=5242880 # 5MB
MAX_TIER_ITEMS=50
MAX_TIERS=10
# Performance
AUTO_SAVE_INTERVAL=30000 # 30 seconds- Create a PostgreSQL-compatible database (Supabase, Neon, Railway, local, etc.)
- Get your project URL and anon key from your provider's dashboard (if required)
Production (Object Storage):
- Create an account on a provider proposing a S3 compatible Object Storage service
- Create an Object Storage subscription
- Create a bucket for your images
- Get your access keys from the dashboard
Development (Local MinIO): See docs/MINIO_SETUP.md for detailed MinIO configuration.
-
Prepare environment
cp .env.example .env.production # Configure production variables -
Build and deploy
DOCKER_TARGET=production docker-compose --profile production up --build -d
-
Access your app
- HTTP:
http://your-domain - HTTPS:
https://your-domain(automatic with Caddy) - Admin:
http://your-domain:2019(Caddy admin)
- HTTP:
NODE_ENV=production
DOMAIN=your-domain.com
HTTP_PORT=80
HTTPS_PORT=443
# Use production database and storage
DATABASE_URL=https://your-production-db.example.co
S3_ENDPOINT=https://your-production-storage.com# Development
bun run dev # Start development server
bun run build # Build for production
bun run start # Start production server
# Code Quality
bun run lint # Run ESLint
bun run lint:fix # Fix ESLint issues
bun run format # Format with Prettier
bun run format:check # Check formatting
bun run type-check # Run TypeScript checks
bun run quality # Run all quality checks
# Testing
bun run test # Run tests
bun run test:watch # Run tests in watch mode
bun run test:coverage # Run tests with coveragesrc/
├── core/ # Business logic and entities
├── infrastructure/ # External services (database, storage)
├── presentation/ # Pages and layouts
├── features/ # Feature-specific components
├── shared/ # Shared utilities and UI components
└── app/ # Application providers and configuration
- Define entities in
src/core/entities/ - Create use cases in
src/core/use-cases/ - Implement infrastructure in
src/infrastructure/ - Build UI components in
src/features/ - Write tests for all layers
Run the test suite:
# Unit tests
bun run test
# Watch mode
bun run test:watch
# Coverage report
bun run test:coverage- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- MinIO Setup - Local storage configuration
Build fails with TypeScript errors:
bun run type-checkImages not uploading:
- Check S3 credentials and bucket permissions
- Verify file size limits (default 5MB)
- Ensure bucket CORS is configured
Database connection issues:
- Verify database URL and anon key
- Check database permissions
- Ensure tables exist
Container won't start:
# Check logs
docker-compose logs app
# Rebuild containers
docker-compose build --no-cacheMinIO access issues:
# Check MinIO logs
docker-compose logs minio
# Reset MinIO data
docker-compose down -v
docker-compose --profile local-storage upThis project is licensed under the MIT License - see the LICENSE file for details.
- React - UI library
- TypeScript - Type safety
- Bun - Fast runtime and package manager
- TailwindCSS - Utility-first CSS
- PostgreSQL - Database system
- MinIO - S3-compatible object storage
- Caddy - Modern web server