@frankhoodbs/uppy-uploader

🧩 Utility to easily initialize an uploader based on Uppy, with full support for multipart uploads to AWS S3 using custom APIs.

📦 Installation

# with npm
npm install @frankhoodbs/uppy-uploader

# or with yarn
yarn add @frankhoodbs/uppy-uploader

# or with pnpm
pnpm add @frankhoodbs/uppy-uploader

🚀 Package Purpose

This package exports a function that instantiates and configures Uppy to upload files to AWS S3. It automatically handles:

• "simple" uploads (non-multipart) to an application endpoint
• multipart uploads (start, part signing, list, complete, abort) with custom endpoints
• parameter serialization via application/x-www-form-urlencoded
• automatic multipart threshold for files > 100 MiB

🧠 Usage (quick example)

import initializeUppy from '@frankhoodbs/uppy-uploader';
import Dashboard from '@uppy/dashboard';
import '@uppy/core/dist/style.css';
import '@uppy/dashboard/dist/style.css';

// Initialize Uppy with custom configuration
const uppy = initializeUppy({
  fieldName: 'file',
  api: '/api/upload/123e4567-e89b-12d3-a456-426614174000',
  multipartStartApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/start',
  multipartUploadPartApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/part/__PART_NUMBER__',
  multipartCompleteApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/complete',
  multipartAbortApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/abort',
  multipartListApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/list',
  uppyConfig: {
    restrictions: {
      maxFileSize: 50 * 1024 * 1024, // 50 MB
      maxNumberOfFiles: 3,
      allowedFileTypes: ['image/*', 'application/pdf'],
    },
    autoProceed: true,
  },
});

// (Optional) Add Uppy Dashboard UI
uppy.use(Dashboard, {
  inline: true,
  target: '#uploader',
  proudlyDisplayPoweredByUppy: false,
});

// Example: handle completion
uppy.on('complete', (result) => {
  console.log('Upload complete:', result.successful);
});

⚙️ API & Placeholders

You can use the following placeholders in endpoint URLs; they are automatically replaced:

• __UPLOADID__ → replaced with encodeURIComponent(uploadId)
• __PART_NUMBER__ → replaced with the part number (string)

Example endpoints:

• Simple upload (POST): /api/upload/123e4567-e89b-12d3-a456-426614174000
• Multipart start (POST): /api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/start
• Multipart sign part (GET): /api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/part/__PART_NUMBER__?key=<encodedKey>
• Multipart list parts (GET): /api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/list?key=<encodedKey>
• Multipart complete (POST): /api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/complete
• Multipart abort (DELETE): /api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/abort?key=<encodedKey>

📑 Types and Options

UppyUploaderOptions

| Field | Type | Req. | Description | |--------------------------|----------------------|:----:|------------------------------------------------------------------| | fieldName | string | ❌ | The name of the backend file field | | api | string | ✅ | Endpoint for non-multipart uploads | | multipartStartApiEndpoint | string | ✅ | Endpoint to start multipart upload | | multipartUploadPartApiEndpoint | string | ✅ | Endpoint to sign each part | | multipartCompleteApiEndpoint | string | ✅ | Endpoint to complete multipart upload | | multipartAbortApiEndpoint | string | ✅ | Endpoint to abort multipart upload | | multipartListApiEndpoint | string | ✅ | Endpoint to retrieve the list of uploaded parts | | uppyConfig | UppyUploaderConfig | ✅ | Uppy configuration (restrictions, general options, events, etc.) |

UppyUploaderConfig

Extends UppyOptions<Meta, Record<string, never>>, with optional restrictions:

interface UppyUploaderConfig
  extends Omit<UppyOptions<Meta, Record<string, never>>, 'restrictions'> {
  restrictions?: Partial<Restrictions>;
}

🔒 Behavior & Security

• The content type is automatically set to file.type.
• Parameters for simple uploads are sent as application/x-www-form-urlencoded:
  • filename, content_type, field.
• In multipart mode:
  • createMultipartUpload sends filename, content_type, field.
  • signPart requires uploadId, key, partNumber and returns signing data expected by @uppy/aws-s3.
  • listParts returns a part list from your backend.
  • completeMultipartUpload sends a POST with { parts, key }.
  • abortMultipartUpload sends a DELETE.

Note: The library does not manage S3 policies or credentials — your backend endpoints must provide valid signed URLs.

🧩 Internal Workflow (overview)

• Creates a Uppy instance using uppyConfig
• Registers the @uppy/aws-s3 plugin
• Automatically decides shouldUseMultipart if file.size > 100 * MiB (100 MiB)
• Implements all plugin callbacks:
  • getUploadParameters
  • createMultipartUpload
  • signPart
  • listParts
  • completeMultipartUpload
  • abortMultipartUpload

🧪 Integration Example

In Vue (minimal example)

<template>
  <div id="uploader" />
</template>

<script setup lang="ts">
import { onMounted, onBeforeUnmount } from 'vue';
import initializeUppy from '@frankhoodbs/uppy-uploader';
import Dashboard from '@uppy/dashboard';
import '@uppy/core/dist/style.css';
import '@uppy/dashboard/dist/style.css';

let uppy: any;

onMounted(() => {
  uppy = initializeUppy({
    fieldName: 'file',
    api: '/api/upload/123e4567-e89b-12d3-a456-426614174000',
    multipartStartApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/start',
    multipartUploadPartApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/part/__PART_NUMBER__',
    multipartCompleteApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/complete',
    multipartAbortApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/abort',
    multipartListApiEndpoint: '/api/upload/123e4567-e89b-12d3-a456-426614174000/multipart/__UPLOADID__/list',
    uppyConfig: { autoProceed: true },
  });

  uppy.use(Dashboard, { inline: true, target: '#uploader' });
});

onBeforeUnmount(() => {
  uppy?.close?.();
});
</script>

❗️ Error Handling

• Every fetch checks response.ok and throws Error('Unsuccessful request', { cause: response }) on failure.
• Some functions call signal?.throwIfAborted() when available.
• Make sure your API endpoints return the expected JSON schema for @uppy/aws-s3.

🔧 Available Scripts (from package.json)

| Script | Description | |-------------------|------------------------------------------------------| | dev | Runs Vite in development mode | | clean | Removes the dist/ folder | | build | Compiles TypeScript into dist/ | | minify | Minifies the output using @frankhoodbs/uglify-js | | lint | Runs ESLint | | prettier-format | Applies Prettier formatting to .ts files in src/ |

📁 Project Structure (simplified)

.
├── src/
│   └── index.ts
├── dist/
├── package.json
└── README.md

📚 Main Dependencies

• @uppy/core
• @uppy/aws-s3
• (optional for UI) @uppy/dashboard

🪪 License

ISC – © Frankhood Business Solutions s.r.l.

📫 Contact

• Website: https://www.frankhood.it/
• Email: [email protected]