@capgo/capacitor-zip

Zip and unzip files in your Capacitor app for free on iOS and Android, and unzip in the browser on the web.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-zip in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-zip to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Zip: zip() compresses a file or a folder into an archive.
• Unzip: unzip() extracts an archive to a destination folder.
• Native libraries: ZIPFoundation on iOS and zip4j on Android.
• Passwords on Android: AES-256 encrypted archives when you pass a password.
• Web unzip: unzip() works in the browser and downloads each file separately, without the folder structure.
• Progress events: addListener('progress', ...) reports byte and file progress during zip and unzip (web: unzip only).
• Platforms: iOS, Android and Web. zip() is not available on web.

Why Capacitor Zip?

A free and open-source alternative for ZIP file operations in Capacitor apps:

• Native Performance - Uses platform-native ZIP libraries for fast compression
• Password Protection - AES encryption support on Android (iOS coming soon)
• Cross-platform - Works on iOS, Android, and Web
• TypeScript - Full TypeScript definitions included
• Modern APIs - Built with latest Capacitor 7 standards

Perfect for apps that need file compression, backup functionality, data export, or secure file transfers.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/zip/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-zip` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-zip
npx cap sync

Progress listener

import { CapacitorZip } from '@capgo/capacitor-zip';

const listener = await CapacitorZip.addListener('progress', (event) => {
  const percent = Math.round(event.progress * 100);
  console.log(`${event.operation} ${percent}%`, event.currentFile ?? '');
});

try {
  await CapacitorZip.zip({ source: '/path/to/folder', destination: '/path/to/archive.zip' });
} finally {
  await listener.remove();
}

API

• addListener('progress', ...)
• zip(...)
• unzip(...)
• getPluginVersion()
• Interfaces

Capacitor Zip Plugin for compressing and extracting zip archives.

Provides native ZIP file operations with platform-specific implementations:

• iOS: Uses ZIPFoundation (password protection not supported)
• Android: Uses zip4j with AES encryption support
• Web: Uses zip.js (unzip only, triggers downloads)

addListener('progress', ...)

addListener(eventName: 'progress', listenerFunc: (event: ZipProgressEvent) => void) => Promise<PluginListenerHandle>

Listen for progress updates while zip or unzip is running.

Register before starting the operation. Events are best-effort on web (unzip only). Each event includes operationId, source, and destination so you can filter when several operations run at once. Pass a unique operationId per call if you supply your own.

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

zip(...)

zip(options: ZipOptions) => Promise<void>

Compress a file or directory to create a ZIP archive.

Creates a compressed archive from a source file or directory. The archive will include the entire directory structure if the source is a folder.

Platform-specific notes:

• iOS: Password protection is not supported. If a password is provided, it will be ignored and a warning will be logged.
• Android: Supports AES-256 encryption when a password is provided.
• Web: Not supported. Throws an error if called.

Since: 7.0.0

unzip(...)

unzip(options: UnzipOptions) => Promise<void>

Extract a ZIP archive to a specified destination directory.

Extracts all files and folders from a ZIP archive while preserving the directory structure. Creates the destination directory if it doesn't exist.

Platform-specific notes:

• iOS: Supports standard ZIP archives. Password-protected archives are not supported; a provided password is ignored.
• Android: Supports AES-encrypted archives with password. Includes zip slip vulnerability protection.
• Web: Downloads each file individually to the browser's download folder. Cannot create a directory structure.

Since: 7.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native plugin version.

Returns the version of the native plugin code, which follows the Capacitor major version (e.g., 7.0.0 for Capacitor 7.x).

Returns: Promise<{ version: string; }>

Since: 7.0.0

Interfaces

PluginListenerHandle

ZipProgressEvent

Progress payload emitted on the progress listener during zip and unzip.

ZipOptions

Options for creating a ZIP archive.

UnzipOptions

Options for extracting a ZIP archive.

Usage

Basic Zip

import { CapacitorZip } from '@capgo/capacitor-zip';

// Zip a directory
await CapacitorZip.zip({
  source: '/path/to/directory',
  destination: '/path/to/output.zip'
});

// Zip a single file
await CapacitorZip.zip({
  source: '/path/to/file.txt',
  destination: '/path/to/output.zip'
});

Zip with Password

import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.zip({
  source: '/path/to/directory',
  destination: '/path/to/output.zip',
  password: 'mySecurePassword123'
});

Basic Unzip

import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.unzip({
  source: '/path/to/archive.zip',
  destination: '/path/to/extract'
});

Unzip with Password

import { CapacitorZip } from '@capgo/capacitor-zip';

await CapacitorZip.unzip({
  source: '/path/to/encrypted.zip',
  destination: '/path/to/extract',
  password: 'mySecurePassword123'
});

Get Plugin Version

import { CapacitorZip } from '@capgo/capacitor-zip';

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

Platform Support

Platform Limitations

iOS

• Password-protected archives are not supported with the current ZIPFoundation library
• If a password is provided, it will be ignored with a console warning

Android

• Full support for password-protected ZIP archives using AES encryption via zip4j

Web

The web implementation has the following limitations:

• Zip: Not supported (throws an error)
• Unzip: Triggers browser downloads for each file in the archive
• Password: Password-protected archives are not supported

For production web applications, consider using a server-side solution for zip operations.

File Paths

iOS

Use paths relative to the app's document directory or full paths:

import { Filesystem, Directory } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({
  directory: Directory.Documents,
  path: 'myfile.zip'
});

await CapacitorZip.unzip({
  source: uri,
  destination: Directory.Documents + '/extracted'
});

Android

Use paths relative to the app's data directory or full paths:

import { Filesystem, Directory } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'myfile.zip'
});

await CapacitorZip.unzip({
  source: uri,
  destination: Directory.Data + '/extracted'
});

Error Handling

import { CapacitorZip } from '@capgo/capacitor-zip';

try {
  await CapacitorZip.zip({
    source: '/path/to/directory',
    destination: '/path/to/output.zip'
  });
  console.log('Zip created successfully!');
} catch (error) {
  console.error('Failed to create zip:', error);
}

Dependencies

iOS

• ZIPFoundation - Provides ZIP compression with AES encryption

Android

• zip4j - Provides password-protected ZIP support

Web

• zip.js - JavaScript ZIP library (limited functionality)

License

MIT

Credits

Created by Martin Donadieu for Capgo