Plugins

Extend FluxMedia with custom functionality using the plugin system.

Installation


pnpm add @fluxmedia/plugins
 
# For image optimization:
pnpm add sharp

Using Plugins


import { MediaUploader } from '@fluxmedia/core';
import { 
  createFileValidationPlugin,
  createAnalyticsPlugin 
} from '@fluxmedia/plugins';
 
const uploader = new MediaUploader(provider);
 
// Add plugins
await uploader.use(createFileValidationPlugin({
  maxSize: 10 * 1024 * 1024,
  allowedTypes: ['image/*']
}));
 
await uploader.use(createAnalyticsPlugin({
  logLevel: 'info'
}));

Available Plugins

File Validation

Validates files before upload.


import { createFileValidationPlugin } from '@fluxmedia/plugins';
 
const plugin = createFileValidationPlugin({
  allowedTypes: ['image/*', 'video/mp4'],
  maxSize: 10 * 1024 * 1024, // 10MB
  blockedExtensions: ['.exe', '.bat'],
  useMagicBytes: true,
});

Image Optimization (Server-side)

Optimizes images using sharp before upload.


import { createImageOptimizationPlugin } from '@fluxmedia/plugins';
 
const plugin = createImageOptimizationPlugin({
  maxWidth: 2000,
  maxHeight: 2000,
  quality: 0.85,
  format: 'webp',
});

Metadata Extraction

Extracts EXIF data, dimensions, and file hashes.


import { createMetadataExtractionPlugin } from '@fluxmedia/plugins';
 
const plugin = createMetadataExtractionPlugin({
  extractExif: true,
  extractDimensions: true,
  hashFile: true,
});

Analytics

Logs and tracks upload operations with strongly-typed events.


import { createAnalyticsPlugin, type TrackFunction } from '@fluxmedia/plugins';
 
const plugin = createAnalyticsPlugin({
  environment: 'production',
  logLevel: 'info',
  // Typed track function - TypeScript verifies event/data match
  track: (event, data) => {
    // event: 'media.upload.started' | 'media.upload.completed' | 'media.delete.completed' | 'media.error'
    myAnalytics.track(event, data);
  },
});

Event Types: media.upload.started, media.upload.completed, media.delete.completed, media.error

Retry

Provides automatic retry with exponential backoff. Use createRetryPlugin with withRetry:


import { createRetryPlugin, withRetry, getRetryConfig } from '@fluxmedia/plugins';
 
// 1. Add retry plugin to store configuration
await uploader.use(createRetryPlugin({
  maxRetries: 3,
  retryDelay: 1000,
  exponentialBackoff: true,
  onRetry: (attempt, error, delay) => {
    console.log(`Retry ${attempt} after ${delay}ms`);
  }
}));
 
// 2. Use withRetry for automatic retry logic
const result = await withRetry(
  () => uploader.upload(file),
  { maxRetries: 3, exponentialBackoff: true }
);

Creating Custom Plugins


import { createPlugin } from '@fluxmedia/core';
 
const myPlugin = createPlugin('my-plugin', {
  beforeUpload: async (file, options) => {
    console.log('Uploading:', file);
    return { file, options };
  },
  afterUpload: async (result) => {
    console.log('Uploaded:', result.url);
    return result;
  },
  onError: async (error, context) => {
    console.error('Failed:', error.message);
  },
});

Plugin Lifecycle


interface FluxMediaPlugin {
  name: string;
  version?: string;
  hooks: PluginHooks;
  init?: () => Promise<void> | void;    // Called on register
  destroy?: () => Promise<void> | void; // Called on unregister
}

Plugin Hooks

beforeUpload - Modify file/options before upload
afterUpload - Modify result after upload
onError - Handle upload errors
beforeDelete - Modify ID before deletion
afterDelete - Run code after deletion
beforeGetUrl - Modify URL generation

Plugin Manager API


// Check if plugin exists
uploader.plugins.has('logger');
 
// Get a plugin
const plugin = uploader.plugins.get('logger');
 
// Unregister
await uploader.plugins.unregister('logger');
 
// Get all plugins
const allPlugins = uploader.plugins.getAll();
 
// Clear all
await uploader.plugins.clear();

Plugin Override Behavior

When registering plugins with the same name, the last one wins:


// First version
await uploader.use(createPlugin('analytics', {
  afterUpload: async (result) => {
    sendToAnalytics('v1', result);
    return result;
  },
}));
 
// Override with new version
await uploader.use(createPlugin('analytics', {
  afterUpload: async (result) => {
    sendToAnalytics('v2', result); // This one runs
    return result;
  },
}));