Skip to Content
FluxMedia

FluxMedia

Provider-agnostic media uploads for JavaScript

FluxMedia is a unified API for uploading images, videos, and files to any cloud storage provider. Write your upload logic once, use it with any provider.

Features

  • Provider Agnostic - Use Cloudinary, S3, R2, and more with one interface
  • Unified API - Same code works with any provider
  • Streaming Support - Upload from File, Buffer, Readable, or ReadableStream
  • Fallback Providers - Automatic failover when primary provider fails
  • Transactional Uploads - Atomic upload-then-commit with rollback support
  • React Hooks - useMediaUpload for easy integration
  • Plugin System - Extensible with lifecycle hooks, optional plugins, and graceful degradation
  • Structured Errors - Typed error codes with partial upload recovery
  • Tree-shakeable - Only bundle what you use
  • Fully Tested - 179 tests across all packages

Quick Start

npm install @fluxmedia/core @fluxmedia/cloudinary
import { MediaUploader } from '@fluxmedia/core';
import { CloudinaryProvider } from '@fluxmedia/cloudinary';
 
const uploader = new MediaUploader(
  new CloudinaryProvider({
    cloudName: 'your-cloud',
    apiKey: 'your-key',
    apiSecret: 'your-secret',
  })
);
 
const result = await uploader.upload(file, {
  folder: 'uploads',
  transformation: { width: 800, format: 'webp' },
});
 
console.log(result.url);
console.log(result.storageKey); // Provider-specific storage key

Packages

PackageDescription
@fluxmedia/coreCore types, MediaUploader, plugin system, file type detection
@fluxmedia/cloudinaryCloudinary provider with transformations
@fluxmedia/s3AWS S3 provider
@fluxmedia/r2Cloudflare R2 provider
@fluxmedia/reactReact hooks and components
@fluxmedia/pluginsOfficial plugins: validation, optimization, metadata, analytics, retry

Why FluxMedia?

Before FluxMedia

// Tightly coupled to Cloudinary
import cloudinary from 'cloudinary';
cloudinary.v2.uploader.upload(file, { folder: 'uploads' });
 
// Migrating to S3? Rewrite everything...

With FluxMedia

// Provider-agnostic
import { MediaUploader } from '@fluxmedia/core';
import { CloudinaryProvider } from '@fluxmedia/cloudinary';
// OR
import { S3Provider } from '@fluxmedia/s3';
 
// Same API, consistent behavior
const uploader = new MediaUploader(new CloudinaryProvider({ ... }));
// OR
const uploader = new MediaUploader(new S3Provider({ ... }));
 
// With fallback provider for resilience
const uploader = new MediaUploader(
  new CloudinaryProvider({ ... }),
  [],
  { fallbackProvider: new S3Provider({ ... }) }
);
Last updated on
API Reference