UpChunk Documentation

To use UpChunk in a standard JavaScript environment, import the module and call createUpload. You can provide the endpoint as a string or a function that returns a promise resolving to the URL. Subscribe to events like progress, error, and success to manage the UI state.

import * as UpChunk from '@mux/upchunk';

const picker = document.getElementById('picker');

picker.onchange = () => {
  const getUploadUrl = () =>
    fetch('/the-endpoint-above').then((res) =>
      res.ok ? res.text() : throw new Error('Error getting an upload URL :(')
    );

  const upload = UpChunk.createUpload({
    endpoint: getUploadUrl,
    file: picker.files[0],
    chunkSize: 30720, // Uploads the file in ~30 MB chunks
  });

  // subscribe to events
  upload.on('error', (err) => {
    console.error('💥 🙀', err.detail);
  });

  upload.on('progress', (progress) => {
    console.log(`So far we've uploaded ${progress.detail}% of this file.`);
  });

  upload.on('success', () => {
    console.log("Wrap it up, we're done here. 👋");
  });
};

In a React application, you can manage upload progress and status messages using useState. Call createUpload within an event handler (like onChange of a file input) and attach event listeners to update the component state.

import React, { useState } from 'react';
import * as UpChunk from '@mux/upchunk';

function Page() {
  const [progress, setProgress] = useState(0);
  const [statusMessage, setStatusMessage] = useState(null);

  const handleUpload = async (inputRef) => {
    try {
      const response = await fetch('/your-server-endpoint', { method: 'POST' });
      const url = await response.text();

      const upload = UpChunk.createUpload({
        endpoint: url, // Authenticated url
        file: inputRef.files[0], // File object with your video file’s properties
        chunkSize: 30720, // Uploads the file in ~30 MB chunks
      });

      // Subscribe to events
      upload.on('error', (error) => {
        setStatusMessage(error.detail);
      });

      upload.on('progress', (progress) => {
        setProgress(progress.detail);
      });

      upload.on('success', () => {
        setStatusMessage("Wrap it up, we're done here. 👋");
      });
    } catch (error) {
      setErrorMessage(error);
    }
  };

  return (
    <div className="page-container">
      <h1 className="page-container">File upload button</h1>
      <label htmlFor="file-picker">Select a video file:</label>
      <input
        type="file"
        onChange={(e) => handleUpload(e.target)}
        id="file-picker"
        name="file-picker"
      />

      <label htmlFor="upload-progress">Downloading progress:</label>
      <progress value={progress} max="100" />

      <em>{statusMessage}</em>
    </div>
  );
}

export default Page;

Returns an instance of UpChunk and begins uploading the specified File.

Options:

• endpoint (string | function, required): URL to upload to. If a function, it receives the file as a parameter and must return a promise resolving to the URL string.
• file (File, required): The file to upload.
• headers (Object | function): Headers to include with each PUT request. Can be an object, a function returning an object, or a function returning a promise of an object.
• chunkSize (integer, default: 30720): Size in kB of chunks. Must be a multiple of 256.
• maxFileSize (integer): Maximum size of the input file in kb.
• attempts (integer, default: 5): Number of retries for retriable failures.
• delayBeforeAttempt (number, default: 1.0): Seconds to wait before retrying a chunk.
• retryCodes (number[], default: [408, 502, 503, 504]): HTTP Status codes that trigger a retry.
• method (string, default: PUT): HTTP method (PUT, PATCH, or POST).
• dynamicChunkSize (boolean, default: false): Whether to scale chunkSize based on network conditions.
• maxChunkSize (integer, default: 512000): Max size in kB when dynamicChunkSize is true.
• minChunkSize (integer, default: 256): Min size in kB when dynamicChunkSize is true.
• useLargeFileWorkaround (boolean, default: false): Fallback to reading entire file into memory for unreliable stream support.

When calling createUpload(options), you can provide the following configuration keys:

const options: UpChunkOptions = {
  endpoint: async (file) => {
    const response = await fetch('/get-url');
    const { url } = await response.json();
    return url;
  },
  file: myFile,
  method: 'POST',
  headers: () => ({ 'Authorization': 'Bearer token' }),
  chunkSize: 512,
  dynamicChunkSize: true,
};

The UpChunk instance is an EventTarget. You can subscribe to various lifecycle events using .on(eventName, callback) or .once(eventName, callback). Use .off(eventName, callback) to unsubscribe.

Available Events:

• attempt: Dispatched when a chunk upload attempt begins. Detail includes chunkNumber, totalChunks, and chunkSize.
• attemptFailure: Dispatched when a chunk upload fails but retries are still available. Detail includes message, chunkNumber, attemptsLeft, and response.
• chunkSuccess: Dispatched when a single chunk is successfully uploaded. Detail includes chunk, chunkSize, attempts, timeInterval, and response.
• error: Dispatched when the upload fails permanently. Detail includes message, chunk, attempts, and response.
• offline: Dispatched when the browser detects the user has gone offline.
• online: Dispatched when the browser detects the user is back online.
• progress: Dispatched during upload. Detail is a number representing the percentage (0-100).
• success: Dispatched when the entire file has been successfully uploaded.

const upload = createUpload(options);

upload.on('progress', (event) => {
  console.log(`Upload progress: ${event.detail}%`);
});

upload.on('success', () => {
  console.log('Upload finished successfully!');
});

upload.on('error', (event) => {
  console.error('Upload failed:', event.detail.message);
});