Gallery

A modern, full-stack image gallery application built with React, TanStack Router, and Supabase. Upload, organize, and showcase your favorite photographs with a beautiful, responsive interface.

✨ Features

• 🔐 Secure Authentication - User authentication powered by Clerk
• 📸 Image Upload - Drag & drop or click to upload high-quality images
• 🖼️ Interactive Gallery - Grid view with modal lightbox for detailed viewing
• 🗑️ Image Management - Delete unwanted images with confirmation
• 📱 Responsive Design - Beautiful UI that works on all devices
• 🔍 Image Navigation - Keyboard shortcuts for easy browsing (← → Arrow keys, Esc to close)
• ⚡ Fast Performance - Optimized loading with React Query caching
• 🌙 Dark Theme - Sleek dark interface for comfortable viewing

🛠️ Tech Stack

Frontend

• React 19 - Latest React with modern features
• TypeScript - Type-safe development
• TanStack Router - Type-safe routing
• TanStack Query - Server state management and caching
• Tailwind CSS - Utility-first CSS framework
• Vite - Fast build tool and development server

Backend & Database

• TanStack Start - Full-stack React framework
• Neon PostgreSQL - Serverless PostgreSQL database
• Supabase Storage - File storage for images
• tRPC - End-to-end type-safe APIs

Authentication & Deployment

• Clerk - User authentication and management
• Vinxi - Full-stack deployment

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• Bun package manager
• PostgreSQL database (Neon recommended)
• Supabase account for file storage
• Clerk account for authentication

Environment Variables

Create a .env.local file in the root directory:

# Database
VITE_DATABASE_URL=your_neon_database_url

# Supabase Storage
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_SUPABASE_BUCKET_NAME=your_bucket_name

# Clerk Authentication
VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

Installation

1. Clone the repository

   git clone <repository-url>
   cd Gallery

2. Install dependencies

   bun install

3. Set up the database

   CREATE TABLE gallery (
     id VARCHAR PRIMARY KEY,
     url VARCHAR NOT NULL,
     name VARCHAR NOT NULL,
     date TIMESTAMP DEFAULT NOW()
   );

4. Configure Supabase Storage

   • Create a new storage bucket in Supabase
   • Set up appropriate policies for authenticated users

5. Start the development server

   bun run dev

6. Open your browser Navigate to http://localhost:3000

📁 Project Structure

src/
├── components/          # React components
│   ├── Gallery.tsx     # Main gallery grid and modal
│   ├── Header.tsx      # Navigation header
│   ├── Upload.tsx      # Image upload component
│   ├── Delete.tsx      # Image deletion component
│   ├── Landing.tsx     # Landing page for unauthenticated users
│   └── Image.tsx       # TypeScript interfaces
├── routes/             # TanStack Router routes
│   ├── index.tsx       # Home page route
│   ├── album.tsx       # Album route (work in progress)
│   └── __root.tsx      # Root layout
├── lib/                # Utility libraries
│   ├── neon.ts         # Database connection
│   └── supabase.ts     # Supabase client
├── integrations/       # Third-party integrations
│   ├── tanstack-query/ # React Query setup
│   └── trpc/          # tRPC configuration
└── styles.css          # Global styles

🖥️ Usage

Uploading Images

1. Sign in using the authentication modal
2. Click the upload button or drag and drop images
3. Supported formats: JPG, PNG, WebP, GIF
4. Images are automatically optimized and stored securely

Viewing Images

1. Click any image in the grid to open the lightbox modal
2. Navigate using arrow keys or on-screen buttons
3. Press Escape to close the modal
4. Image details are displayed in the modal header

Managing Images

1. Delete images using the trash icon in the modal
2. Confirmation required before permanent deletion
3. Images are removed from both storage and database

🔧 Available Scripts

# Development
bun run dev          # Start development server

# Building
bun run build        # Build for production
bun run start        # Start production server

# Testing
bun run test         # Run test suite

# Preview
bun run serve        # Preview production build

🏗️ Architecture

Authentication Flow

1. Landing page shown to unauthenticated users
2. Clerk handles sign-in/sign-up process
3. Protected routes require authentication
4. User-specific galleries based on Clerk user ID

Data Flow

1. Images uploaded to Supabase Storage
2. Metadata stored in Neon PostgreSQL
3. React Query manages server state and caching
4. Real-time updates when images are added/deleted

Performance Optimizations

• Lazy loading for gallery images
• Image prefetching for modal navigation
• Optimistic updates for immediate UI feedback
• Efficient caching with React Query

🔒 Security

• User authentication required for all operations
• User isolation - users can only access their own images
• Secure file upload with type validation
• Environment variables for sensitive configuration
• HTTPS enforced in production

🌐 Deployment

Recommended Platforms

• Vercel - Optimal for TanStack Start applications
• Netlify - Alternative deployment option
• Railway - Full-stack deployment with database

Deployment Steps

1. Build the application

   bun run build

2. Configure environment variables on your platform

3. Deploy using your preferred method

4. Set up custom domain (optional)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the documentation above
2. Search existing issues in the repository
3. Create a new issue with detailed information
4. Include error messages and steps to reproduce

🔮 Roadmap

• Album organization - Group images into albums
• Image search - Search by filename or metadata
• Bulk operations - Select and delete multiple images
• Image editing - Basic crop and filter operations
• Sharing - Share galleries with other users
• Mobile app - React Native companion app

---

Built with ❤️ using modern web technologies