c2stack/cc-photo-tools repository overview

⁠CC Photo Tools

A professional suite of browser-based photo editing and manipulation tools. Create stunning photo grids with customizable layouts, all running directly in your browser with no uploads required.

⁠✨ Features

• Photo Grid Generator: Create beautiful grid layouts from multiple photos
• Drag & Drop Upload: Easy photo upload with drag-and-drop support
• Customizable Layouts: Adjust columns, gaps, and aspect ratios
• Multiple Aspect Ratios: Choose from 1:1, 4:3, 3:4, 16:9, 9:16, or original dimensions
• Visual Preview: Live preview of your grid as you adjust settings
• Drag to Reorder: Rearrange photos by dragging them into position
• Background Color: Customize the gap color between photos
• High-Quality Export: Download your grid as a PNG image
• Privacy-First: All processing happens in your browser - no server uploads
• Responsive Design: Works seamlessly on desktop and mobile devices

⁠🚀 Getting Started

⁠Prerequisites

• Bun⁠ runtime installed

⁠Installation

1. Clone the repository and navigate to the app directory:

cd apps/cc-photo-tools

1. Install dependencies:

bun install

⁠Development

Run the development server:

bun dev

The app will be available at http://localhost:5173 (or another port if 5173 is in use).

⁠🏗️ Building For Production

Build the application for production:

bun build

Preview the production build:

bun preview

⁠📖 Usage

⁠Photo Grid Generator

1. Upload Photos: Click the upload button or drag and drop multiple images
2. Adjust Settings:
   • Set the number of columns (1-8)
   • Adjust gap size between photos (0-50px)
   • Choose your preferred aspect ratio
   • Select a background color for gaps
3. Arrange Photos: Drag photos to reorder them in the collection
4. Generate Grid: Click "Generate Grid" to create the layout
5. Download: Click "Download Grid" to save your creation as a PNG

⁠Supported Image Formats

• JPEG/JPG
• PNG
• WebP
• GIF
• BMP
• And other browser-supported image formats

⁠🧪 Testing

Run the test suite:

bun test

This project uses Vitest⁠ for testing.

⁠🛠️ Tech Stack

• React 19⁠ - UI framework
• TanStack Router⁠ - File-based routing
• Vite⁠ - Build tool and dev server
• Tailwind CSS 4⁠ - Styling
• Lucide React⁠ - Icon library
• HTML Canvas API - Image processing and grid generation
• Bun - JavaScript runtime and package manager

⁠📁 Project Structure

cc-photo-tools/
├── src/
│   ├── routes/              # TanStack Router file-based routes
│   │   ├── __root.tsx      # Root layout
│   │   ├── index.tsx       # Homepage with tool cards
│   │   └── photo-grid.tsx  # Photo grid generator
│   ├── components/         # React components
│   │   ├── app-sidebar.tsx
│   │   └── photo-grid/     # Photo grid specific components
│   ├── hooks/              # Custom React hooks
│   │   └── usePhotoGrid.ts # Photo grid logic
│   ├── types.ts            # TypeScript type definitions
│   ├── main.tsx            # Application entry point
│   └── styles.css          # Global styles
├── public/                 # Static assets
└── index.html              # HTML template

⁠🎨 Features Deep Dive

⁠Photo Grid Generator

The Photo Grid Generator uses the HTML5 Canvas API to create high-quality photo grids with precise control over layout and spacing:

• Smart Image Fitting: Images are automatically cropped using object-fit: cover logic to fill each cell perfectly
• Flexible Layouts: Support for 1-8 columns with automatic row calculation
• Custom Spacing: Adjust gaps from 0-50 pixels for tight or spacious layouts
• Aspect Ratio Control: Six preset aspect ratios plus original dimensions
• High Resolution: Generated grids maintain high quality for printing or web use

⁠🐳 Docker

A Dockerfile is included for containerized deployment. Build and run with:

docker build -t cc-photo-tools .
docker run -p 8080:80 cc-photo-tools

⁠🤝 Contributing

This is part of the cc-web-tools monorepo. See the main repository for contribution guidelines.

⁠📄 License

Part of the cc-web-tools project.