{"id":20980863,"url":"https://github.com/cap-go/capacitor-uploader","last_synced_at":"2026-02-26T18:27:50.930Z","repository":{"id":255442176,"uuid":"851611239","full_name":"Cap-go/capacitor-uploader","owner":"Cap-go","description":"Capacitor plugin to upload file in native layer","archived":false,"fork":false,"pushed_at":"2026-02-16T11:41:12.000Z","size":1059,"stargazers_count":19,"open_issues_count":12,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T14:39:03.265Z","etag":null,"topics":["capacitor","capacitor-plugin","plugin"],"latest_commit_sha":null,"homepage":"https://capgo.app","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cap-go.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"Cap-go","patreon":null,"open_collective":"capgo","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2024-09-03T12:14:14.000Z","updated_at":"2026-02-16T11:40:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"73f2fe04-cf77-4964-89df-f032affd5795","html_url":"https://github.com/Cap-go/capacitor-uploader","commit_stats":{"total_commits":132,"total_committers":4,"mean_commits":33.0,"dds":0.5606060606060606,"last_synced_commit":"e8ce600622bc81123e818b07c8067c91f160192d"},"previous_names":["cap-go/capacitor-uploader"],"tags_count":126,"template":false,"template_full_name":null,"purl":"pkg:github/Cap-go/capacitor-uploader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cap-go","download_url":"https://codeload.github.com/Cap-go/capacitor-uploader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-uploader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29642905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T05:21:04.652Z","status":"ssl_error","status_checked_at":"2026-02-20T05:21:04.238Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capacitor","capacitor-plugin","plugin"],"created_at":"2024-11-19T05:31:01.454Z","updated_at":"2026-02-20T06:01:27.039Z","avatar_url":"https://github.com/Cap-go.png","language":"Java","funding_links":["https://github.com/sponsors/Cap-go","https://opencollective.com/capgo"],"categories":[],"sub_categories":[],"readme":"# @capgo/capacitor-uploader\nUpload files in the background with progress tracking, resumable uploads, and network-aware handling for Capacitor apps.\n\n\n \u003ca href=\"https://capgo.app/\"\u003e\u003cimg src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/\u003e\u003c/a\u003e\n \n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/?ref=plugin_uploader\"\u003e ➡️ Get Instant updates for your App with Capgo\u003c/a\u003e\u003c/h2\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/consulting/?ref=plugin_uploader\"\u003e Missing a feature? We’ll build the plugin for you 💪\u003c/a\u003e\u003c/h2\u003e\n\u003c/div\u003e\n\n## Uploader Plugin\n\nThis plugin provides a flexible way to upload natively files to various servers, including S3 with presigned URLs.\n\nCan be used in combination with the [Capacitor Camera preview](https://github.com/Cap-go/camera-preview) To upload file in reliable manner instead of reading them in buffer of webview and then upload in JS.\n\nOn the web, file paths support IndexedDB (IDB) semantic paths using the following format:  \n`idb://[database-name]/[collection-name]/[key]`  \nThis allows seamless integration with IndexedDB for storing and retrieving files.\n\n## Documentation\n\nThe most complete doc is available here: https://capgo.app/docs/plugins/uploader/\n\n## Compatibility\n\n| Plugin version | Capacitor compatibility | Maintained |\n| -------------- | ----------------------- | ---------- |\n| v8.\\*.\\*       | v8.\\*.\\*                | ✅          |\n| v7.\\*.\\*       | v7.\\*.\\*                | On demand   |\n| v6.\\*.\\*       | v6.\\*.\\*                | ❌          |\n| v5.\\*.\\*       | v5.\\*.\\*                | ❌          |\n\n\u003e **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.\n\n## Install\n\n```bash\nnpm install @capgo/capacitor-uploader\nnpx cap sync\n```\n\n## Android\n\nAdd the following to your `AndroidManifest.xml` file:\n\n```xml\n    \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n```\n\n## Example S3 upload\n\n```typescript\nimport { Uploader } from '@capgo/capacitor-uploader';\n\nasync function uploadToS3(filePath: string, presignedUrl: string, fields: Record\u003cstring, string\u003e) {\n  try {\n    const { id } = await Uploader.startUpload({\n      filePath: filePath,\n      serverUrl: presignedUrl,\n      method: 'PUT',\n      parameters: fields,\n      notificationTitle: 'Uploading to S3'\n    });\n\n    console.log('Upload started with ID:', id);\n\n    // Listen for upload events\n    Uploader.addListener('events', (event: UploadEvent) =\u003e {\n      if (event.name === 'uploading') {\n        console.log(`Upload progress: ${event.payload.percent}%`);\n      } else if (event.name === 'completed') {\n        console.log('Upload completed successfully');\n      } else if (event.name === 'failed') {\n        console.error('Upload failed:', event.payload.error);\n      }\n    });\n\n  } catch (error) {\n    console.error('Failed to start upload:', error);\n  }\n}\n\n```\n\n### Example upload to a custom server\n\n```typescript\nimport { Uploader } from '@capgo/capacitor-uploader';\n\nasync function uploadToCustomServer(filePath: string, serverUrl: string) {\n  try {\n    // Start the upload\n    const { id } = await Uploader.startUpload({\n      filePath: filePath,\n      serverUrl: serverUrl,\n      method: 'POST',\n      headers: {\n        'Authorization': 'Bearer your-auth-token-here'\n      },\n      parameters: {\n        'user_id': '12345',\n        'file_type': 'image'\n      },\n      notificationTitle: 'Uploading to Custom Server',\n      maxRetries: 3\n    });\n\n    console.log('Upload started with ID:', id);\n\n    // Listen for upload events\n    Uploader.addListener('events', (event) =\u003e {\n      switch (event.name) {\n        case 'uploading':\n          console.log(`Upload progress: ${event.payload.percent}%`);\n          break;\n        case 'completed':\n          console.log('Upload completed successfully');\n          console.log('Server response status code:', event.payload.statusCode);\n          break;\n        case 'failed':\n          console.error('Upload failed:', event.payload.error);\n          break;\n      }\n    });\n\n    // Optional: Remove the upload if needed\n    // await Uploader.removeUpload({ id: id });\n\n  } catch (error) {\n    console.error('Failed to start upload:', error);\n  }\n}\n\n// Usage\nconst filePath = 'file:///path/to/your/file.jpg';\nconst serverUrl = 'https://your-custom-server.com/upload';\nuploadToCustomServer(filePath, serverUrl);\n\n```\n\n### Example with Capacitor Camera preview\n\nDocumentation for the [Capacitor Camera preview](https://github.com/Cap-go/camera-preview)\n\n```typescript\n  import { CameraPreview } from '@capgo/camera-preview'\n  import { Uploader } from '@capgo/capacitor-uploader';\n\n\n  async function record() {\n    await CameraPreview.startRecordVideo({ storeToFile: true })\n    await new Promise(resolve =\u003e setTimeout(resolve, 5000))\n    const fileUrl = await CameraPreview.stopRecordVideo()\n    console.log(fileUrl.videoFilePath)\n    await uploadVideo(fileUrl.videoFilePath)\n  }\n\n  async function uploadVideo(filePath: string) {\n    Uploader.addListener('events', (event) =\u003e {\n      switch (event.name) {\n        case 'uploading':\n          console.log(`Upload progress: ${event.payload.percent}%`);\n          break;\n        case 'completed':\n          console.log('Upload completed successfully');\n          console.log('Server response status code:', event.payload.statusCode);\n          break;\n        case 'failed':\n          console.error('Upload failed:', event.payload.error);\n          break;\n      }\n    });\n    try {\n      const result = await Uploader.startUpload({\n        filePath,\n        serverUrl: 'S#_PRESIGNED_URL',\n        method: 'PUT',\n        headers: {\n          'Content-Type': 'video/mp4',\n        },\n        mimeType: 'video/mp4',\n      });\n      console.log('Video uploaded successfully:', result.id);\n    } catch (error) {\n      console.error('Error uploading video:', error);\n      throw error;\n    }\n  }\n```\n\n## API\n\n\u003cdocgen-index\u003e\n\n* [`startUpload(...)`](#startupload)\n* [`removeUpload(...)`](#removeupload)\n* [`addListener('events', ...)`](#addlistenerevents-)\n* [`getPluginVersion()`](#getpluginversion)\n* [Interfaces](#interfaces)\n\n\u003c/docgen-index\u003e\n\n\u003cdocgen-api\u003e\n\u003c!--Update the source file JSDoc comments and rerun docgen to update the docs below--\u003e\n\nCapacitor Uploader Plugin for uploading files with background support and progress tracking.\n\n### startUpload(...)\n\n```typescript\nstartUpload(options: uploadOption) =\u003e Promise\u003c{ id: string; }\u003e\n```\n\nStart uploading a file to a server.\n\nThe upload will continue in the background even if the app is closed or backgrounded.\nListen to upload events to track progress, completion, or failure.\n\n| Param         | Type                                                  | Description                    |\n| ------------- | ----------------------------------------------------- | ------------------------------ |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#uploadoption\"\u003euploadOption\u003c/a\u003e\u003c/code\u003e | - Configuration for the upload |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;{ id: string; }\u0026gt;\u003c/code\u003e\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### removeUpload(...)\n\n```typescript\nremoveUpload(options: { id: string; }) =\u003e Promise\u003cvoid\u003e\n```\n\nCancel and remove an ongoing upload.\n\nThis will stop the upload if it's in progress and clean up resources.\n\n| Param         | Type                         | Description                                 |\n| ------------- | ---------------------------- | ------------------------------------------- |\n| **`options`** | \u003ccode\u003e{ id: string; }\u003c/code\u003e | - Object containing the upload ID to remove |\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### addListener('events', ...)\n\n```typescript\naddListener(eventName: 'events', listenerFunc: (state: UploadEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\nListen for upload progress and status events.\n\nEvents are fired for:\n- Upload progress updates (with percent)\n- Upload completion (with statusCode)\n- Upload failure (with error and statusCode)\n\n| Param              | Type                                                                    | Description                                 |\n| ------------------ | ----------------------------------------------------------------------- | ------------------------------------------- |\n| **`eventName`**    | \u003ccode\u003e'events'\u003c/code\u003e                                                   | - Must be 'events'                          |\n| **`listenerFunc`** | \u003ccode\u003e(state: \u003ca href=\"#uploadevent\"\u003eUploadEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e | - Callback function to handle upload events |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### getPluginVersion()\n\n```typescript\ngetPluginVersion() =\u003e Promise\u003c{ version: string; }\u003e\n```\n\nGet the native Capacitor plugin version.\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;{ version: string; }\u0026gt;\u003c/code\u003e\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### Interfaces\n\n\n#### uploadOption\n\nConfiguration options for uploading a file.\n\n| Prop                    | Type                                    | Description                                                                                                                                               | Default                  | Since |\n| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |\n| **`filePath`**          | \u003ccode\u003estring\u003c/code\u003e                     | The local file path of the file to upload. Can be a file:// URL or an absolute path.                                                                      |                          | 0.0.1 |\n| **`serverUrl`**         | \u003ccode\u003estring\u003c/code\u003e                     | The server URL endpoint where the file should be uploaded.                                                                                                |                          | 0.0.1 |\n| **`notificationTitle`** | \u003ccode\u003estring\u003c/code\u003e                     | The title of the upload notification shown to the user. Android only.                                                                                     | \u003ccode\u003e'Uploading'\u003c/code\u003e | 0.0.1 |\n| **`headers`**           | \u003ccode\u003e{ [key: string]: string; }\u003c/code\u003e | HTTP headers to send with the upload request. Useful for authentication tokens, content types, etc.                                                       |                          | 0.0.1 |\n| **`method`**            | \u003ccode\u003e'PUT' \\| 'POST'\u003c/code\u003e            | The HTTP method to use for the upload request.                                                                                                            | \u003ccode\u003e'POST'\u003c/code\u003e      | 0.0.1 |\n| **`mimeType`**          | \u003ccode\u003estring\u003c/code\u003e                     | The MIME type of the file being uploaded. If not specified, the plugin will attempt to determine it automatically.                                        |                          | 0.0.1 |\n| **`parameters`**        | \u003ccode\u003e{ [key: string]: string; }\u003c/code\u003e | Additional form parameters to send with the upload request. These will be included as form data in multipart uploads.                                     |                          | 0.0.1 |\n| **`maxRetries`**        | \u003ccode\u003enumber\u003c/code\u003e                     | The maximum number of times to retry the upload if it fails.                                                                                              | \u003ccode\u003e0\u003c/code\u003e           | 0.0.1 |\n| **`uploadType`**        | \u003ccode\u003e'binary' \\| 'multipart'\u003c/code\u003e    | 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 | \u003ccode\u003e'binary'\u003c/code\u003e    | 0.0.2 |\n| **`fileField`**         | \u003ccode\u003estring\u003c/code\u003e                     | The form field name for the file when using multipart upload type. Only used when uploadType is 'multipart'.                                              | \u003ccode\u003e'file'\u003c/code\u003e      | 0.0.2 |\n\n\n#### PluginListenerHandle\n\n| Prop         | Type                                      |\n| ------------ | ----------------------------------------- |\n| **`remove`** | \u003ccode\u003e() =\u0026gt; Promise\u0026lt;void\u0026gt;\u003c/code\u003e |\n\n\n#### UploadEvent\n\nEvent emitted during the upload lifecycle.\n\n| Prop          | Type                                                                    | Description                                                                                                                                                | Since |\n| ------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |\n| **`name`**    | \u003ccode\u003e'uploading' \\| 'completed' \\| 'failed'\u003c/code\u003e                     | The current status of the upload. - 'uploading': Upload is in progress - 'completed': Upload finished successfully - 'failed': Upload encountered an error | 0.0.1 |\n| **`payload`** | \u003ccode\u003e{ percent?: number; error?: string; statusCode?: number; }\u003c/code\u003e | Additional data about the upload event.                                                                                                                    | 0.0.1 |\n| **`id`**      | \u003ccode\u003estring\u003c/code\u003e                                                     | Unique identifier for this upload task.                                                                                                                    | 0.0.1 |\n\n\u003c/docgen-api\u003e\n\n### Credits:\n\nFor the inspiration and the code on ios: https://github.com/Vydia/react-native-background-upload/tree/master\nFor the API definition: https://www.npmjs.com/package/cordova-plugin-background-upload-put-s3\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcap-go%2Fcapacitor-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-uploader/lists"}