@frankhoodbs/use-uppy-uploader

🧩 Vue 3 Composable to easily mount and manage an Uppy uploader instance using @frankhoodbs/uppy-uploader.

📦 Installation

# with npm
npm install @frankhoodbs/use-uppy-uploader

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

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

🚀 Package Purpose

This package provides a lightweight Vue 3 composable that automatically mounts and destroys an Uppy uploader instance using the initializeUppy helper from @frankhoodbs/uppy-uploader.

It simplifies the integration of Uppy within the Vue lifecycle (onMounted / onUnmounted) and makes it easy to extend uploader logic with your own hooks or UI components.

🧠 Usage (basic example)

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

<script setup lang="ts">
import { Dashboard } from '@uppy/dashboard';
import useUppyUploader from '@frankhoodbs/use-uppy-uploader';
import '@uppy/core/dist/style.css';
import '@uppy/dashboard/dist/style.css';

// Initialize and automatically mount the uploader
useUppyUploader(
  {
    fieldName: 'file',
    uuid: '123e4567-e89b-12d3-a456-426614174000',
    api: '/api/upload/__UUID__',
    multipartStartApi: '/api/upload/__UUID__/multipart/start',
    multipartUploadPartApi: '/api/upload/__UUID__/multipart/__UPLOADID__/part/__PART_NUMBER__',
    multipartCompleteApi: '/api/upload/__UUID__/multipart/__UPLOADID__/complete',
    multipartAbortApi: '/api/upload/__UUID__/multipart/__UPLOADID__/abort',
    multipartListApi: '/api/upload/__UUID__/multipart/__UPLOADID__/list',
    uppyConfig: {
      restrictions: {
        maxFileSize: 50 * 1024 * 1024, // 50 MB
        maxNumberOfFiles: 3,
        allowedFileTypes: ['image/*', 'application/pdf'],
      },
      autoProceed: true,
    },
  },
  (uppy) => {
    // Called after Uppy is mounted
    uppy.use(Dashboard, {
      inline: true,
      target: '#uploader',
      proudlyDisplayPoweredByUppy: false,
    });

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

⚙️ API Reference

useUppyUploader(uppyData, afterMounted?)

Parameters

| Parameter | Type | Required | Description | |----------------|-----------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------| | uppyData | UppyUploaderOptions | ✅ | Configuration object passed directly to initializeUppy | | afterMounted | (uppy: Uppy) => void | ❌ | Optional callback executed after the Uppy instance is created and mounted |

Returns

| Type | Description | |----------------|----------------------------------------------------------------------| | Uppy \| null | Returns the Uppy instance reference (initially null until mounted) |

🧩 Lifecycle Behavior

This composable automatically manages the uploader lifecycle:

• 🟢 onMounted → Creates the Uppy instance via initializeUppy()
• 🟣 afterMounted callback (optional) → Invoked once the instance is ready
• 🔴 onUnmounted → Automatically destroys the instance to free memory

Example internal flow:

onMounted(() => {
  uppy = initializeUppy(uppyData);
  if (typeof afterMounted === 'function') {
    afterMounted(uppy);
  }
});

onUnmounted(() => {
  if (uppy !== null) {
    uppy.destroy();
  }
});

🔌 Integration Examples

Example with a Custom Component

<template>
  <div id="upload-area"></div>
</template>

<script setup lang="ts">
import { Dashboard } from '@uppy/dashboard';
import useUppyUploader from '@frankhoodbs/use-uppy-uploader';

useUppyUploader(
  {
    fieldName: 'avatar',
    uuid: 'user-uuid',
    api: '/api/upload/__UUID__',
    uppyConfig: { autoProceed: true },
  },
  (uppy) => {
    uppy.use(Dashboard, { inline: true, target: '#upload-area' });
  },
);
</script>

📚 Dependencies

• Vue 3
• @frankhoodbs/uppy-uploader
• @uppy/core
• @uppy/dashboard (optional for UI)

🔧 Available Scripts

| Script | Description | |-------------------|----------------------------------------------------| | dev | Run Vite in development mode | | build | Compile TypeScript to dist/ | | clean | Remove the dist/ folder | | minify | Minify build output using @frankhoodbs/uglify-js | | lint | Run ESLint | | prettier-format | Apply Prettier formatting to .ts files |

📁 Project Structure (simplified)

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

🪪 License

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

📫 Contact

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