Plugins

The plugin system provides hooks into every upload lifecycle event. Register plugins to add logging, analytics, file processing, validation, and queue optimization.

Using Plugins

import {
  FirebaseUploadManager,
  LoggingPlugin,
  AnalyticsPlugin
} from 'svelte-firebase-upload';

const manager = new FirebaseUploadManager();

await manager.registerPlugin(new LoggingPlugin({ logLevel: 'info' }));
await manager.registerPlugin(new AnalyticsPlugin());

Managing Plugins

// Enable/disable — use the plugin's .name property, not the class name
await manager.setPluginEnabled('logging', false);

// Unregister
await manager.unregisterPlugin('logging');

// List all
manager.getAllPlugins();     // [{ name, plugin, config }]
manager.getEnabledPlugins(); // Only active ones

Built-in Plugins

Logging

Logs all upload events to the console and optionally to storage.

const logger = new LoggingPlugin({
  logLevel: 'info',    // 'debug' | 'info' | 'warn' | 'error'
  logToConsole: true,
  logToStorage: false
});

await manager.registerPlugin(logger);

// Access logs
logger.getLogs();
logger.clearLogs();

Analytics

Tracks upload metrics like success rate, timing, and error breakdown.

const analytics = new AnalyticsPlugin();
await manager.registerPlugin(analytics);

const metrics = analytics.getMetrics();
// { successRate, averageUploadTime, errorBreakdown, ... }

analytics.resetMetrics();

File Processing

Compresses and resizes images before upload.

const processor = new FileProcessingPlugin({
  compressImages: true,
  maxImageWidth: 1920,
  maxImageHeight: 1080,
  imageQuality: 0.8
});

await manager.registerPlugin(processor);

Validation

Adds file signature verification beyond basic MIME type checks.

const validator = new ValidationEnhancementPlugin();
await manager.registerPlugin(validator);

Queue Optimization

Optimizes upload order by file size and priority for faster throughput.

const optimizer = new QueueOptimizationPlugin();
await manager.registerPlugin(optimizer);

Custom Plugins

Implement the UploadPlugin interface to create your own:

import type { UploadPlugin, UploadItem, ValidationResult } from 'svelte-firebase-upload';

const myPlugin: UploadPlugin = {
  name: 'MyCustomPlugin',
  version: '1.0.0',
  description: 'Does something custom',

  // Lifecycle hooks
  async onInitialize(manager) {
    console.log('Plugin initialized');
  },

  async onDestroy() {
    console.log('Plugin destroyed');
  },

  // File hooks — modify file/options before adding
  async beforeFileAdd(file, options) {
    return { file, options }; // Return modified or original
  },
  async afterFileAdd(item) {},

  // Validation hooks
  async beforeValidation(file, rules) {
    return { file, rules };
  },
  async afterValidation(file, result) {},

  // Upload hooks
  async beforeUpload(item) {
    return item; // Return modified or original
  },
  async onUploadStart(item) {},
  async onUploadProgress(item, progress) {},
  async onUploadComplete(item, result) {},
  async onUploadError(item, error) {},

  // Queue hooks
  async beforeQueueProcess(queue) {
    return queue; // Reorder or filter
  },
  async afterQueueProcess(queue) {},

  // State hooks
  async onStatusChange(item, oldStatus, newStatus) {},
  async onManagerStateChange(state) {},
  async onError(error, context) {},
};

await manager.registerPlugin(myPlugin);

Plugin Event Types

Event	When it fires
beforeFileAdd	Before a file is added to the queue
afterFileAdd	After a file is added to the queue
beforeValidation	Before file validation runs
afterValidation	After validation completes
beforeUpload	Before upload starts
onUploadStart	When upload begins
onUploadProgress	On progress update
onUploadComplete	When upload succeeds
onUploadError	When upload fails
beforeQueueProcess	Before the queue is processed
afterQueueProcess	After queue processing
onStatusChange	When a file’s status changes
onManagerStateChange	When manager state changes
onError	On any error