Getting Started

# Core (required)
pnpm add @fluxmedia/core
 
# Pick a provider
pnpm add @fluxmedia/cloudinary  # Full featured with transformations
pnpm add @fluxmedia/s3          # AWS S3
pnpm add @fluxmedia/r2          # Cloudflare R2
 
# Optional: Official plugins
pnpm add @fluxmedia/plugins
 
# Optional: React integration
pnpm add @fluxmedia/react

import { MediaUploader } from '@fluxmedia/core';
import { CloudinaryProvider } from '@fluxmedia/cloudinary';
 
// Create uploader with your provider
const uploader = new MediaUploader(
  new CloudinaryProvider({
    cloudName: process.env.CLOUDINARY_CLOUD_NAME!,
    apiKey: process.env.CLOUDINARY_API_KEY!,
    apiSecret: process.env.CLOUDINARY_API_SECRET!,
  })
);
 
// Upload a file
const result = await uploader.upload(fileBuffer, {
  folder: 'user-avatars',
  filename: 'avatar-123',
});
 
console.log(result.url); // https://res.cloudinary.com/...
console.log(result.id); // user-avatars/avatar-123
console.log(result.storageKey); // Provider-specific storage key
console.log(result.format); // jpg

import { createReadStream } from 'fs';
 
// Upload from Node.js Readable stream
const stream = createReadStream('/path/to/large-file.mp4');
const result = await uploader.upload(stream, {
  folder: 'videos',
  contentType: 'video/mp4',
});
 
// Upload from web ReadableStream
const response = await fetch('https://example.com/image.jpg');
const result = await uploader.upload(response.body!, {
  folder: 'imports',
});

import { useMediaUpload } from '@fluxmedia/react';
 
function UploadButton() {
  const { upload, uploading, progress, result, error } = useMediaUpload({
    mode: 'signed',
    signUrlEndpoint: '/api/upload/sign',
  });
 
  return (
    <input
      type="file"
      disabled={uploading}
      onChange={(e) => {
        const file = e.target.files?.[0];
        if (file) upload(file);
      }}
    />
  );
}

// Before: Cloudinary
const uploader = new MediaUploader(
  new CloudinaryProvider({ ... })
);
 
// Need S3 instead? Same interface!
import { S3Provider } from '@fluxmedia/s3';
 
const uploader = new MediaUploader(
  new S3Provider({
    region: 'us-east-1',
    bucket: 'my-bucket',
    accessKeyId: process.env.AWS_ACCESS_KEY!,
    secretAccessKey: process.env.AWS_SECRET_KEY!,
  })
);
 
// All your upload code stays exactly the same
await uploader.upload(file, { folder: 'uploads' });

import { MediaUploader, MediaErrorCode } from '@fluxmedia/core';
 
const uploader = new MediaUploader(
  new CloudinaryProvider({ ... }),  // Primary
  [],                                // No plugins
  {
    fallbackProvider: new S3Provider({ ... }),  // Fallback
    fallbackOnErrors: [
      MediaErrorCode.NETWORK_ERROR,
      MediaErrorCode.RATE_LIMITED,
      MediaErrorCode.PROVIDER_ERROR,
    ],
    onFallback: (error, fallback) => {
      console.warn(`Using ${fallback.name} due to: ${error.message}`);
    },
  }
);
 
// If Cloudinary fails with a qualifying error, S3 is used automatically
const result = await uploader.upload(file, { folder: 'uploads' });

const controller = new AbortController();
 
// Cancel after 30 seconds
setTimeout(() => controller.abort(), 30000);
 
const result = await uploader.upload(file, {
  folder: 'uploads',
  signal: controller.signal,
});

const result = await uploader.upload(file, {
  folder: 'uploads',
  onProgress: (percent) => {
    // Normalized 0-100 percentage
    progressBar.style.width = `${percent}%`;
  },
  onByteProgress: (loaded, total) => {
    // Raw byte counts for precise tracking
    console.log(`${loaded}/${total} bytes`);
  },
});

if (uploader.supports('transformations.resize')) {
  // Apply resize transformation
  const url = uploader.getUrl(id, { width: 200, height: 200 });
}
 
if (uploader.supports('capabilities.videoProcessing')) {
  // Provider supports video processing
}