FluxMedia
Copy page
Open in ChatGPTOpen in Claude

FluxMedia

Unified 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, and it works with every provider.

Features

  • Unified API - Use Cloudinary, S3, R2, and more with one interface
  • Consistent Interface - 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
yarn add @fluxmedia/core @fluxmedia/cloudinary
pnpm add @fluxmedia/core @fluxmedia/cloudinary
bun add @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

Package Description
@fluxmedia/core Core types, MediaUploader, plugin system, file type detection
@fluxmedia/cloudinary Cloudinary provider with transformations
@fluxmedia/s3 AWS S3 provider
@fluxmedia/r2 Cloudflare R2 provider
@fluxmedia/react React hooks and components
@fluxmedia/plugins Official plugins: validation, optimization, metadata, analytics, retry

Why FluxMedia?

Before FluxMedia

// Cloudinary SDK
import cloudinary from 'cloudinary';
cloudinary.v2.uploader.upload(file, { folder: 'uploads' });

// S3 SDK — completely different API
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
// ... lots of boilerplate

With FluxMedia

// Unified interface
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({ ... }) }
);