@capgo/capacitor-uploader

Upload files in the background with progress tracking, resumable uploads, and network-aware handling for Capacitor apps.

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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

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.

| Param | Type | Description | | ------------- | ----------------------------------------------------- | ------------------------------ | | options | uploadOption | - Configuration for the upload |

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.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | ---------------------------------------- | | options | UploadMultipartOptions | - Configuration for the multipart upload |

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.

| Param | Type | Description | | ------------- | ---------------------------- | ------------------------------------------- | | options | { id: string; } | - Object containing the upload ID to remove |

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)

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------- | | eventName | 'events' | - Must be 'events' | | listenerFunc | (state: UploadEvent) => void | - Callback function to handle upload events |

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.

| Param | Type | Description | | ------------- | --------------------------------- | ---------------------------------------------- | | options | { eventId: string; } | - Object containing the eventId to acknowledge |

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

| Prop | Type | Description | Default | Since | | ----------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----- | | filePath | string | The local file path of the file to upload. Can be a file:// URL or an absolute path. If you need to upload multiple files in a single multipart request, use files. | | 0.0.1 | | files | UploadFileOption[] | Multiple files to upload in a single request. When provided, uploads are sent as multipart/form-data with one part per file. Use fieldName to control each part name (e.g. images[]). Note: PUT uploads (e.g. presigned S3 URLs) only support a single file. | | 0.0.3 | | serverUrl | string | The server URL endpoint where the file should be uploaded. | | 0.0.1 | | notificationTitle | string | The title of the upload notification shown to the user. Android only. | 'Uploading' | 0.0.1 | | headers | { [key: string]: string; } | HTTP headers to send with the upload request. Useful for authentication tokens, content types, etc. | | 0.0.1 | | method | 'PUT' | 'POST' | The HTTP method to use for the upload request. | 'POST' | 0.0.1 | | mimeType | string | The MIME type of the file being uploaded. If not specified, the plugin will attempt to determine it automatically. | | 0.0.1 | | parameters | { [key: string]: string; } | Additional form parameters to send with the upload request. These will be included as form data in multipart uploads. | | 0.0.1 | | maxRetries | number | The maximum number of times to retry the upload if it fails. | 0 | 0.0.1 | | uploadType | 'binary' | 'multipart' | The type of upload to perform. - 'binary': Uploads the file as raw binary data in the request body - 'multipart': Uploads the file as multipart/form-data | 'binary' when method is 'PUT', otherwise 'multipart' | 0.0.2 | | fileField | string | The form field name for the file when using multipart upload type. Only used when uploadType is 'multipart'. For multi-file uploads via files, this is used as the default field name when a file entry does not specify fieldName. | 'file' | 0.0.2 |

UploadFileOption

Configuration options for uploading a file.

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | filePath | string | The local file path of the file to upload. Can be a file:// URL or an absolute path. | 0.0.3 | | fieldName | string | The form field name for the file part when using multipart upload. If omitted, uploadOption.fileField is used (defaults to 'file'). | 0.0.3 | | mimeType | string | The MIME type of this file. If not specified, the plugin will attempt to determine it automatically. | 0.0.3 |

UploadMultipartOptions

Options for starting a single-file multipart upload.

| Prop | Type | Description | Since | | --------------- | --------------------------------------- | ------------------------------------------------------------------------------------ | ----- | | url | string | The server URL endpoint where the multipart request should be sent. | 8.3.2 | | filePath | string | The local file path of the file to upload. Can be a file:// URL or an absolute path. | 8.3.2 | | fieldName | string | The form field name for the uploaded file part. | 8.3.2 | | fields | { [key: string]: string; } | Additional form fields to include in the multipart request. | 8.3.2 | | headers | { [key: string]: string; } | HTTP headers to send with the upload request. | 8.3.2 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

UploadEvent

Event emitted during the upload lifecycle.

| Prop | Type | Description | Since | | ------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | name | 'uploading' | 'completed' | 'failed' | The current status of the upload. - 'uploading': Upload is in progress - 'completed': Upload finished successfully - 'failed': Upload encountered an error | 0.0.1 | | payload | { percent?: number; error?: string; statusCode?: number; } | Additional data about the upload event. | 0.0.1 | | id | string | Unique identifier for this upload task. | 0.0.1 | | eventId | string | Unique identifier for this specific event instance. Only present on 'completed' and 'failed' events. Used with acknowledgeEvent() to confirm receipt and remove the event from the plugin cache. Progress ('uploading') events do not have an eventId and are not persisted. | 0.0.2 |

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