Getting Started

Install

bun add @capgo/capacitor-uploader
bunx cap sync

Import

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

API Overview

startUpload

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.

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

const { id } = await Uploader.startUpload({
  filePath: 'file:///path/to/file.jpg',
  serverUrl: 'https://example.com/upload',
  headers: {
    'Authorization': 'Bearer token'
  },
  method: 'POST',
  uploadType: 'multipart',
  fileField: 'photo'
});
console.log('Upload started with ID:', id);

removeUpload

Cancel and remove an ongoing upload.

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

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

await Uploader.removeUpload({ id: 'upload-123' });

Type Reference

uploadOption

Configuration options for uploading a file.

export interface uploadOption {
  /**
   * The local file path of the file to upload.
   * Can be a file:// URL or an absolute path.
   *
   * @since 0.0.1
   */
  filePath: string;

  /**
   * The server URL endpoint where the file should be uploaded.
   *
   * @since 0.0.1
   */
  serverUrl: string;

  /**
   * The title of the upload notification shown to the user.
   * Android only.
   *
   * @default 'Uploading'
   * @since 0.0.1
   */
  notificationTitle?: string;

  /**
   * HTTP headers to send with the upload request.
   * Useful for authentication tokens, content types, etc.
   *
   * @since 0.0.1
   * @example
   * ```typescript
   * headers: {
   *   'Authorization': 'Bearer token123',
   *   'X-Custom-Header': 'value'
   * }
   * ```
   */
  headers: {
    [key: string]: string;
  };

  /**
   * The HTTP method to use for the upload request.
   *
   * @default 'POST'
   * @since 0.0.1
   */
  method?: 'PUT' | 'POST';

  /**
   * The MIME type of the file being uploaded.
   * If not specified, the plugin will attempt to determine it automatically.
   *
   * @since 0.0.1
   * @example 'image/jpeg', 'application/pdf', 'video/mp4'
   */
  mimeType?: string;

  /**
   * Additional form parameters to send with the upload request.
   * These will be included as form data in multipart uploads.
   *
   * @since 0.0.1
   */
  parameters?: { [key: string]: string };

  /**
   * The maximum number of times to retry the upload if it fails.
   *
   * @since 0.0.1
   * @default 0
   */
  maxRetries?: number;

  /**
   * 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
   *
   * @default 'binary'
   * @since 0.0.2
   */
  uploadType?: 'binary' | 'multipart';

  /**
   * The form field name for the file when using multipart upload type.
   * Only used when uploadType is 'multipart'.
   *
   * @default 'file'
   * @since 0.0.2
   */
  fileField?: string;
}

UploadEvent

Event emitted during the upload lifecycle.

export interface UploadEvent {
  /**
   * The current status of the upload.
   * - 'uploading': Upload is in progress
   * - 'completed': Upload finished successfully
   * - 'failed': Upload encountered an error
   *
   * @since 0.0.1
   */
  name: 'uploading' | 'completed' | 'failed';

  /**
   * Additional data about the upload event.
   *
   * @since 0.0.1
   */
  payload: {
    /**
     * Upload progress percentage from 0 to 100.
     * Only present during 'uploading' events.
     *
     * @since 0.0.1
     */
    percent?: number;

    /**
     * Error message if the upload failed.
     * Only present during 'failed' events.
     *
     * @since 0.0.1
     */
    error?: string;

    /**
     * HTTP status code returned by the server.
     * Present during 'completed' and 'failed' events.
     *
     * @since 0.0.1
     */
    statusCode?: number;
  };

  /**
   * Unique identifier for this upload task.
   *
   * @since 0.0.1
   */
  id: string;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-uploader for the native capability in Using @capgo/capacitor-uploader, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.