Express RemoveBG API

A lightweight Express.js API server with TypeScript for background removal using Sharp image processing.

Features

• 🚀 Fast & Lightweight: Express.js with TypeScript
• 🖼️ Image Processing: Sharp-based background removal
• 🌐 CORS Support: Configurable cross-origin requests
• 📁 File Upload: Multer-based multipart handling
• 🔧 Environment Config: Flexible configuration via environment variables
• 🧪 Testing: Jest test suite included
• 🐳 Replit Ready: Optimized for Replit deployment

Quick Start

Local Development

1. Clone and Install

   git clone <your-repo-url>
   cd express-removebg-api
   npm install

2. Environment Setup

   cp env.example .env
   # Edit .env with your configuration

3. Development Server

   npm run dev

4. Build for Production

   npm run build
   npm start

Replit Deployment

1. Import this repository to Replit
2. Replit will automatically install dependencies
3. Click "Run" - the server will start automatically

API Endpoints

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "message": "RemoveBG API is running 🚀",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

Background Removal

POST /api/removebg
Content-Type: multipart/form-data

Parameters:

• file: Image file (JPEG, PNG, WebP, GIF)

cURL Example:

curl -X POST \
  -F "file=@/path/to/your/image.jpg" \
  http://localhost:3000/api/removebg \
  --output removed-bg.png

Response:

• Success: PNG image with transparent background
• Error: JSON error message

Configuration

Environment variables (see env.example):

Variable	Default	Description
PORT	3000	Server port
NODE_ENV	development	Environment mode
ALLOWED_ORIGINS	*	CORS allowed origins (comma-separated)
MAX_FILE_SIZE	10485760	Max file size in bytes (10MB)
ALLOWED_FILE_TYPES	image/jpeg,image/png,image/webp,image/gif	Allowed MIME types
BACKGROUND_REMOVAL_TOLERANCE	20	Color tolerance for background removal

Project Structure

express-removebg-api/
├── src/
│   ├── controllers/          # Request handlers
│   │   └── removebgController.ts
│   ├── routes/              # API routes
│   │   └── api.ts
│   ├── utils/               # Utilities
│   │   └── sharpUtils.ts
│   ├── middleware/          # Custom middleware
│   │   └── cors.ts
│   ├── app.ts              # Express app setup
│   └── server.ts           # Server entry point
├── tests/                  # Test files
├── dist/                   # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Development

Scripts

• npm run dev - Start development server with hot reload
• npm run build - Compile TypeScript to JavaScript
• npm start - Start production server
• npm test - Run test suite
• npm run test:watch - Run tests in watch mode

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Test the API manually
curl http://localhost:3000/api/health

Background Removal Algorithm

The API uses a color-based background removal algorithm:

1. Key Color Detection: Samples the top-left pixel as the background color
2. Color Tolerance: Removes pixels within a configurable color distance
3. Transparency: Converts matching pixels to transparent
4. Output: Returns PNG with alpha channel

Tolerance Configuration

Adjust BACKGROUND_REMOVAL_TOLERANCE environment variable:

• 0-10: Very precise (fewer pixels removed)
• 20-30: Balanced (recommended)
• 40-50: Aggressive (more pixels removed)

Deployment

Replit

• Import repository
• Environment variables are set automatically
• Click "Run" to deploy

Other Platforms

• Heroku: Add Procfile with web: npm start
• Railway: Works out of the box
• DigitalOcean App Platform: Use Node.js buildpack
• Vercel: Add vercel.json configuration

Performance

• Memory Usage: ~30-50MB base + image processing
• Cold Start: ~500ms
• Processing Time: 1-3 seconds per image (depends on size)
• Concurrent Requests: Handles multiple requests efficiently

Troubleshooting

Common Issues

1. "File too large" error

   • Increase MAX_FILE_SIZE environment variable
   • Check platform upload limits

2. "Not allowed by CORS" error

   • Update ALLOWED_ORIGINS environment variable
   • Use * for development, specific domains for production

3. Sharp installation issues

   • Ensure platform supports native Sharp binaries
   • Some serverless platforms may require Sharp layers

Logs

The server provides detailed logging:

• Request logging with timestamps
• Background removal progress
• Error details in development mode

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.