Image Compressor

A robust Node.js application for efficient image compression and format conversion, powered by the Tinify API. Designed with a dual-mode architecture to support both automated local directory monitoring and an intuitive web interface with batch processing capabilities.

Features

• Dual Mode Architecture:
  • Online Mode: Web-based drag-and-drop interface with batch processing support
  • Local Mode: Automated filesystem watcher for background batch processing
• Batch Processing: Compress multiple images simultaneously with progress tracking
• Format Conversion: Support for converting to JPEG, PNG, WebP, and AVIF
• Smart Compression: Lossy compression algorithm that preserves visual quality
• ZIP Downloads: Download all compressed images as a single ZIP file
• Modern UI: Clean, responsive interface with glassmorphism design

Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Services: Tinify API
• Utilities: Chokidar (File Watching), Multer (File Handling), Archiver (ZIP creation)
• Frontend: Vanilla HTML/CSS/JS with Lucide Icons

Quick Start

Prerequisites

• Node.js (v14 or higher)
• A Tinify API key (see below for instructions)

Getting Your Free Tinify API Key

1. Visit TinyPNG Developers: Go to https://tinypng.com/developers
2. Sign Up: Enter your email and name
3. Verify Email: Check your inbox for a verification email
4. Get Your Key: Once verified, you'll receive your API key
5. Free Tier: 500 compressions per month, completely free!

Installation

1. Star & Fork the repository:

   • Visit github.com/jackosei/image-compressor
   • Click ⭐ Star to show your support
   • Click Fork to create your own copy

2. Clone your fork:

   git clone https://github.com/YOUR-USERNAME/image-compressor.git
   cd image-compressor

3. Install dependencies:

   npm install

4. Configure Environment: Create a .env file in the root directory with your Tinify API key:

   TINIFY_KEY=your_api_key_from_tinypng
   # Optional: Set default mode (online/local)
   APP_MODE=online
   # Optional: Set local mode output format
   OUTPUT_FORMAT=original
   # Optional: Set port (default: 3000)
   PORT=3000

5. Start the application:

   npm start

6. Access the web interface: Navigate to http://localhost:3000

Usage

Online Mode (Default)

The web interface supports both single and batch image compression:

Single File:

1. Drag & drop or click to select an image
2. Choose output format (optional)
3. Download compressed image

Batch Processing:

1. Select multiple images (up to 5)
2. Watch real-time compression progress for each file
3. Download individually or all files as ZIP

Local Mode

Enable automated directory monitoring:

npm run local-mode

• Place images in the files/in/ directory
• Compressed files automatically appear in files/out/
• Set output format via OUTPUT_FORMAT in .env

Deployment

This application is designed for modern serverless deployment with separated frontend and backend:

• Frontend: Deploy to Netlify (static site)
• Backend: Deploy to Vercel (serverless functions)

Prerequisites

1. Get Your Free Tinify API Key:

   • Visit https://tinypng.com/developers
   • Sign up with your email
   • You'll receive 500 free compressions per month

2. Install CLI Tools (optional, for local testing):

   npm install -g vercel netlify-cli

Option 1: Deploy Backend to Vercel

1. Push to GitHub:

   git add .
   git commit -m "Prepare for deployment"
   git push origin main

2. Deploy to Vercel:

   • Visit https://vercel.com and sign in with GitHub
   • Click "New Project" and import your repository
   • Vercel will auto-detect the configuration from vercel.json
   • Add environment variable in Vercel dashboard:
     • TINIFY_KEY = your_api_key_here
   • Click "Deploy"
   • Copy your deployment URL (e.g., https://your-app.vercel.app)

3. Test Your Backend:

   # Test the API endpoint
   curl https://your-app.vercel.app/api/compress

Option 2: Deploy Frontend to Netlify

1. Configure API URL:

   • Open public/config.js
   • Set your Vercel backend URL:

     window.API_BASE_URL = "https://your-app.vercel.app";

   • Commit this change:

     git add public/config.js
     git commit -m "Configure production API URL"
     git push

2. Deploy to Netlify:

   • Visit https://netlify.com and sign in with GitHub
   • Click "Add new site" → "Import an existing project"
   • Select your repository
   • Netlify will auto-detect settings from netlify.toml
   • Click "Deploy site"
   • Your site will be live at https://your-site-name.netlify.app

3. Custom Domain (Optional):

   • In Netlify dashboard, go to "Domain settings"
   • Add your custom domain

Option 3: Run Locally for Development

Backend (Vercel Dev Server):

npm run dev:backend

This starts the Vercel development server on http://localhost:3000

Frontend (Netlify Dev Server):

npm run dev:frontend

This serves the frontend files from the public/ directory

Traditional Local Server (original method):

npm start

This runs the Express server with both frontend and backend together on http://localhost:3000

Post-Deployment

After deployment, test your app:

• ✅ Upload a single image
• ✅ Test batch processing (multiple images)
• ✅ Verify format conversion works
• ✅ Test ZIP download

Free Tier Limitations

If you're hosting publicly with your personal API key, consider adding usage limits (as implemented in the app UI) to preserve your 500/month free Tinify credits.

Project Structure

image-compressor/
├── api/                        # Vercel serverless functions (backend)
│   ├── _utils/
│   │   └── tinifyService.js   # Image compression service
│   ├── compress.js            # Single image compression endpoint
│   └── compress-batch.js      # Batch compression endpoint
├── src/
│   ├── modes/
│   │   └── local.js           # Directory watcher (local mode)
│   ├── services/
│   │   └── tinifyService.js   # Service for local mode
│   └── server.js              # Express server (for local dev)
├── public/                     # Frontend (deployed to Netlify)
│   ├── index.html             # Web UI
│   ├── script.js              # Frontend logic
│   ├── style.css              # Styling
│   └── config.js              # API configuration
├── files/
│   ├── in/                    # Input directory (local mode)
│   └── out/                   # Output directory (local mode)
├── vercel.json                # Vercel configuration
├── netlify.toml               # Netlify configuration
└── package.json               # Dependencies and scripts

Configuration Options

Variable	Description	Default
TINIFY_KEY	Your Tinify API key	Required
APP_MODE	Application mode: online or local	online
OUTPUT_FORMAT	Local mode output format	original
PORT	Server port	3000

API Limits

• Free Tier: 500 compressions/month
• Batch Limit: 5 images per batch
• File Size: Maximum 4MB per image
• Supported Formats: JPEG, PNG, WebP

FAQ

Q: Why is the hosted version limited to 5 compressions? A: To protect my personal API credits while offering a free demo.

Q: How do I get unlimited compressions? A: Clone this repo, get your own free Tinify API key, and run it locally!

Q: Can I process more than 5 images at once? A: When running locally, you can modify the batch limit in src/modes/online.js.

Q: Is my data safe? A: Images are processed temporarily and automatically deleted. See our Privacy Policy for details.

Contributing

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

License

MIT License - feel free to use this project for your own purposes!

---

Built with ❤️ by Jack Osei

Get the code: GitHub Repository