https://github.com/Cap-go/capacitor-uploader
Native file upload, upload native file directly in native layer
https://github.com/Cap-go/capacitor-uploader
capacitor capacitor-plugin plugin
Last synced: 9 months ago
JSON representation
Native file upload, upload native file directly in native layer
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-uploader
- Owner: Cap-go
- License: mit
- Created: 2024-09-03T12:14:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-28T23:31:25.000Z (10 months ago)
- Last Synced: 2025-06-05T04:15:03.296Z (9 months ago)
- Topics: capacitor, capacitor-plugin, plugin
- Language: Java
- Homepage: https://capgo.app
- Size: 451 KB
- Stars: 14
- Watchers: 1
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-capacitor - Uploader - Upload file natively. ([Capgo plugins](https://capgo.app/) / Storage & Files)
README
# @capgo/capacitor-uploader
➡️ Get Instant updates for your App with Capgo 🚀
Fix your annoying bug now, Hire a Capacitor expert 💪
## 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](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.
## Install
```bash
npm install @capgo/capacitor-uploader
npx cap sync
```
## Android:
Add the following to your `AndroidManifest.xml` file:
```xml
```
## Exemple S3 upload:
## Example S3 upload:
```typescript
import { Uploader } from '@capgo/capacitor-uploader';
async function uploadToS3(filePath: string, presignedUrl: string, fields: Record) {
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);
}
}
```
### Exemple upload to a custom server:
```typescript
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);
```
### Exemple with Capacitor Camera preview:
Documentation for the [Capacitor Camera preview](https://github.com/Cap-go/camera-preview)
```typescript
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(...)`](#startupload)
* [`removeUpload(...)`](#removeupload)
* [`addListener('events', ...)`](#addlistenerevents-)
* [Interfaces](#interfaces)
### startUpload(...)
```typescript
startUpload(options: uploadOption) => Promise<{ id: string; }>
```
| Param | Type | Description |
| ------------- | ----------------------------------------------------- | ---------------------------------------- |
| **`options`** | uploadOption | uploadOption |
**Returns:** Promise<{ id: string; }>
**Since:** 0.0.1
--------------------
### removeUpload(...)
```typescript
removeUpload(options: { id: string; }) => Promise
```
| Param | Type |
| ------------- | ---------------------------- |
| **`options`** | { id: string; } |
**Since:** 0.0.1
--------------------
### addListener('events', ...)
```typescript
addListener(eventName: "events", listenerFunc: (state: UploadEvent) => void) => Promise
```
| Param | Type |
| ------------------ | ----------------------------------------------------------------------- |
| **`eventName`** | 'events' |
| **`listenerFunc`** | (state: UploadEvent) => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 0.0.1
--------------------
### Interfaces
#### uploadOption
| Prop | Type | Default | Since |
| ----------------------- | --------------------------------------- | ------------------------ | ----- |
| **`filePath`** | string | | 0.0.1 |
| **`serverUrl`** | string | | 0.0.1 |
| **`notificationTitle`** | number | 'Uploading' | 0.0.1 |
| **`headers`** | { [key: string]: string; } | | 0.0.1 |
| **`method`** | 'PUT' \| 'POST' | 'POST' | 0.0.1 |
| **`mimeType`** | string | | 0.0.1 |
| **`parameters`** | { [key: string]: string; } | | 0.0.1 |
| **`maxRetries`** | number | | 0.0.1 |
| **`uploadType`** | 'binary' \| 'multipart' | 'binary' | 0.0.2 |
| **`fileField`** | string | 'file' | 0.0.2 |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| **`remove`** | () => Promise<void> |
#### UploadEvent
| Prop | Type | Description | Default | Since |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------- | ----- |
| **`name`** | 'uploading' \| 'completed' \| 'failed' | Current status of upload, between 0 and 100. | | 0.0.1 |
| **`payload`** | { percent?: number; error?: string; statusCode?: number; } | | { percent: 0, error: '', statusCode: 0 } | 0.0.1 |
| **`id`** | string | | | 0.0.1 |
### 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