@capgo/capacitor-uploader

Upload files from your Capacitor app with native background uploads that keep going when the app is closed, with progress events and retries.

🤖 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-uploader in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-uploader to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Uploads: startUpload() sends a file with PUT or POST, custom headers and parameters.
• Multipart: uploadMultipart() sends a file as multipart/form-data.
• Progress events: the events listener reports progress, completion and errors.
• Control: removeUpload() cancels an upload, maxRetries retries failures.
• Background: a background URLSession on iOS and an upload service with a notification on Android.
• Platforms: iOS, Android and Web. Web uploads with fetch() while the page is open, without native background uploads.

Uploader Plugin

This plugin provides a flexible way to upload natively files to various servers, including S3 with presigned URLs.

Can be used in combination with the Capacitor Camera preview To upload file in reliable manner instead of reading them in buffer of webview and then upload in JS.

On the web, file paths support IndexedDB (IDB) semantic paths using the following format:
idb://[database-name]/[collection-name]/[key]
This allows seamless integration with IndexedDB for storing and retrieving files.

Documentation

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

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-uploader` 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-uploader
npx cap sync

Android

Add the following to your AndroidManifest.xml file:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

iOS

On iOS the plugin uploads through a background URLSession using the identifier CapacitorUploaderBackgroundSession.

Uploads often work without extra Info.plist keys. To allow the system to wake your app when background transfers finish, add the fetch background mode:

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
</array>

Do not add the processing background mode for this plugin alone. App Store Connect requires BGTaskSchedulerPermittedIdentifiers whenever processing is declared, and this plugin does not register BGTaskScheduler tasks. If your app already includes processing (for example from older documentation) and validation fails, add:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>CapacitorUploaderBackgroundSession</string>
</array>

See issue #115 for context.

Example S3 upload

import { Uploader } from '@capgo/capacitor-uploader';

async function uploadToS3(filePath: string, presignedUrl: string, fields: Record<string, string>) {
  try {
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: presignedUrl,
      method: 'PUT',
      parameters: fields,
      notificationTitle: 'Uploading to S3'
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event: UploadEvent) => {
      if (event.name === 'uploading') {
        console.log(`Upload progress: ${event.payload.percent}%`);
      } else if (event.name === 'completed') {
        console.log('Upload completed successfully');
      } else if (event.name === 'failed') {
        console.error('Upload failed:', event.payload.error);
      }
    });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

Example upload to a custom server

import { Uploader } from '@capgo/capacitor-uploader';

async function uploadToCustomServer(filePath: string, serverUrl: string) {
  try {
    // Start the upload
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: serverUrl,
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-auth-token-here'
      },
      parameters: {
        'user_id': '12345',
        'file_type': 'image'
      },
      notificationTitle: 'Uploading to Custom Server',
      maxRetries: 3
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });

    // Optional: Remove the upload if needed
    // await Uploader.removeUpload({ id: id });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

// Usage
const filePath = 'file:///path/to/your/file.jpg';
const serverUrl = 'https://your-custom-server.com/upload';
uploadToCustomServer(filePath, serverUrl);

Example multi-file multipart upload

import { Uploader } from '@capgo/capacitor-uploader';

const { id } = await Uploader.startUpload({
  serverUrl: 'https://api.example.com/upload',
  method: 'POST',
  uploadType: 'multipart',
  files: [
    { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
    { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
  ],
  parameters: { albumId: '7' },
  headers: { Authorization: 'Bearer token' },
});
console.log('Upload started with ID:', id);

Example with Capacitor Camera preview

Documentation for the Capacitor Camera preview

  import { CameraPreview } from '@capgo/camera-preview'
  import { Uploader } from '@capgo/capacitor-uploader';


  async function record() {
    await CameraPreview.startRecordVideo({ storeToFile: true })
    await new Promise(resolve => setTimeout(resolve, 5000))
    const fileUrl = await CameraPreview.stopRecordVideo()
    console.log(fileUrl.videoFilePath)
    await uploadVideo(fileUrl.videoFilePath)
  }

  async function uploadVideo(filePath: string) {
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });
    try {
      const result = await Uploader.startUpload({
        filePath,
        serverUrl: 'S#_PRESIGNED_URL',
        method: 'PUT',
        headers: {
          'Content-Type': 'video/mp4',
        },
        mimeType: 'video/mp4',
      });
      console.log('Video uploaded successfully:', result.id);
    } catch (error) {
      console.error('Error uploading video:', error);
      throw error;
    }
  }

API

• startUpload(...)
• uploadMultipart(...)
• removeUpload(...)
• addListener('events', ...)
• acknowledgeEvent(...)
• getPluginVersion()
• Interfaces

Capacitor Uploader Plugin for uploading files with background support and progress tracking.

iOS setup

On iOS the native layer uses a background URLSession with the identifier CapacitorUploaderBackgroundSession. Many apps can upload without adding UIBackgroundModes; add fetch when you need uploads to continue after the app is suspended.

App Store Connect rejects builds that declare UIBackgroundModes → processing without BGTaskSchedulerPermittedIdentifiers. This plugin does not schedule BGTaskScheduler work, so avoid processing unless another feature needs it. If processing is present (for example from older setup guides), include CapacitorUploaderBackgroundSession in BGTaskSchedulerPermittedIdentifiers in your app's Info.plist.

startUpload(...)

startUpload(options: uploadOption) => Promise<{ id: string; }>

Start uploading a file to a server.

The upload will continue in the background even if the app is closed or backgrounded. Listen to upload events to track progress, completion, or failure.

Returns: Promise<{ id: string; }>

Since: 0.0.1

uploadMultipart(...)

uploadMultipart(options: UploadMultipartOptions) => Promise<{ id: string; }>

Start uploading a single file as multipart/form-data.

This is a convenience API for backends that expect a named file field and additional form fields. Existing startUpload binary uploads are unchanged.

Returns: Promise<{ id: string; }>

Since: 8.3.2

removeUpload(...)

removeUpload(options: { id: string; }) => Promise<void>

Cancel and remove an ongoing upload.

This will stop the upload if it's in progress and clean up resources.

Since: 0.0.1

addListener('events', ...)

addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void) => Promise<PluginListenerHandle>

Listen for upload progress and status events.

Events are fired for:

• Upload progress updates (with percent)
• Upload completion (with statusCode)
• Upload failure (with error and statusCode)

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

acknowledgeEvent(...)

acknowledgeEvent(options: { eventId: string; }) => Promise<void>

Acknowledge receipt of an upload event and remove it from the plugin cache.

Completed and failed events are stored in the plugin's persistent cache so they can be re-delivered if the app is closed or backgrounded before the event is processed. Call this method after successfully handling a 'completed' or 'failed' event to prevent it from being re-broadcast the next time the plugin initialises.

Progress ('uploading') events do not have an eventId and do not need to be acknowledged.

Since: 0.0.2

getPluginVersion()

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

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 0.0.1

Interfaces

uploadOption

UploadFileOption

Configuration options for uploading a file.

UploadMultipartOptions

Options for starting a single-file multipart upload.

PluginListenerHandle

UploadEvent

Event emitted during the upload lifecycle.

Credits:

For the inspiration and the code on ios: https://github.com/Vydia/react-native-background-upload/tree/master For the API definition: https://www.npmjs.com/package/cordova-plugin-background-upload-put-s3