Getting Started

1. Install the package

   npm

   npm i @capgo/capacitor-file-compressor

   pnpm

   pnpm add @capgo/capacitor-file-compressor

   yarn

   yarn add @capgo/capacitor-file-compressor

   bun

   bun add @capgo/capacitor-file-compressor

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Platform Support

Platform	Supported Formats	Notes
iOS	JPEG	Only JPEG compression supported
Android	JPEG, WebP	Both formats fully supported
Web	JPEG, WebP	Canvas API-based compression

Note: EXIF metadata is removed during compression on all platforms.

Usage

Import the plugin and compress images:

import { FileCompressor } from '@capgo/capacitor-file-compressor';

// Compress an image
const compressImage = async () => {
  const result = await FileCompressor.compressImage({
    source: 'file:///path/to/image.jpg',
    quality: 0.8,
    width: 1920,
    height: 1080
  });

  console.log('Compressed image path:', result.path);
  console.log('Original size:', result.originalSize);
  console.log('Compressed size:', result.size);
};

API Reference

compressImage(options)

Compresses an image file with specified dimensions and quality settings.

interface CompressImageOptions {
  source: string;           // Path to the image file
  quality?: number;         // 0.0 to 1.0 (default: 0.8)
  width?: number;           // Target width in pixels
  height?: number;          // Target height in pixels
  format?: 'jpeg' | '.webp'; // Output format
}

interface CompressImageResult {
  path: string;             // Path to compressed image
  size: number;             // Compressed file size in bytes
  originalSize: number;     // Original file size in bytes
}

const result = await FileCompressor.compressImage(options);

Important Notes:

• EXIF metadata is removed during compression on all platforms
• Aspect ratio is automatically maintained if only one dimension is provided
• Compressed files are saved to temporary directories on native platforms

getPluginVersion()

Get the native plugin version.

const { version } = await FileCompressor.getPluginVersion();
console.log('Plugin version:', version);

Complete Example

import { FileCompressor } from '@capgo/capacitor-file-compressor';
import { Camera } from '@capacitor/camera';

export class ImageCompressionService {
  async captureAndCompress() {
    try {
      // Take a photo
      const photo = await Camera.getPhoto({
        quality: 100,
        allowEditing: false,
        resultType: 'uri'
      });

      if (!photo.path) {
        throw new Error('No image path');
      }

      // Compress the photo
      const compressed = await FileCompressor.compressImage({
        source: photo.path,
        quality: 0.7,
        width: 1920,
        height: 1080,
        format: 'jpeg'
      });

      console.log(`Compression ratio: ${
        ((1 - compressed.size / compressed.originalSize) * 100).toFixed(1)
      }%`);

      return compressed.path;
    } catch (error) {
      console.error('Compression failed:', error);
      throw error;
    }
  }

  async batchCompress(imagePaths: string[]) {
    const results = [];

    for (const path of imagePaths) {
      try {
        const result = await FileCompressor.compressImage({
          source: path,
          quality: 0.8,
          width: 1280
        });
        results.push(result);
      } catch (error) {
        console.error(`Failed to compress ${path}:`, error);
      }
    }

    return results;
  }
}

Best Practices

1. Quality Settings: Start with 0.8 quality for a good balance between file size and image quality
2. Resize Dimensions: Only specify dimensions when needed - aspect ratio is preserved automatically
3. Format Selection: Use JPEG for photos and WebP for better compression (Android/Web only)
4. Error Handling: Always wrap compression calls in try-catch blocks
5. Cleanup: Remember to clean up temporary files after use

Troubleshooting

Common Issues

Image not compressing: Ensure the source path is valid and accessible Out of memory: Reduce target dimensions or compress images one at a time Format not supported: Check platform support table above