Upload JavaScript SDK

Uploads a file to your account.

This method performs a multipart file upload internally, which provides better performance compared to BasicUpload and FormDataUpload.

Signature

function uploadFile(file: BlobOrFileObject, params?: UploadParams): Promise<UploadedFile>

Parameters

1. file: BLOB or file from an <input type="file" onchange="..." /> event.

2. params: UploadJsParams object (optional).

Result promise

Promise of type UploadedFile

Example

import { Upload } from "upload-js";

const upload = Upload({ apiKey: "free" }); // Replace "free" with your API key.

const onFileSelected = async (event) => {
  const [ file ]    = event.target.files;
  const { fileUrl } = await upload.uploadFile(file, { onProgress });
  alert(`File uploaded: ${fileUrl}`);
}

const onProgress = ({ progress }) => {
  console.log(`File uploading: ${progress}% complete.`)
}

//
// <input type="file" onchange="onFileSelected(event)" />
//

Full example: Upload a File »

Gets the URL for an uploaded file (takes a filePath and returns a URL).

We recommend saving filePath values instead of fileUrl values to your database, as this allows you to change other parts of the URL in future (such as the URL's domain name — if you upgrade to a custom domain — or the "file transformation" part of the URL).

Signature

function url(filePath: string, urlParams?: { auth?: boolean; transformation?: string; }): string

Result

"https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Example

const upload = Upload({ apiKey: "free" }); // Replace "free" with your API key.
const fileUrl = upload.url("/uploads/example.jpg", { transformation: "thumbnail" });
//    fileUrl = "https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Call this method in your client-side code after the user has signed in.

This allows the user to:

• Upload private files based on the permissions inside the UploadJwt (issued by your backend API).

• Download private files based on the permissions inside the UploadJwt (issued by your backend API).

  • The beginAuthSession method starts a cookie-based auth session with the Upload CDN to allow private file downloads via the URL, without needing to pre-sign URLs. For example, if your webpage contains <img> elements that reference private images, you can use beginAuthSession to allow these images to render in the current browser tab.

    You must add ?auth=true to your file URLs when using cookie-based auth.

  • Alternatively, you can download private files by passing your JWT via the Authorization-Token request header, and your public API key via the Authorization request header (see authorization for more information).

The authUrl is a simple GET endpoint you need to implement to return an UploadJwt.

See: Authorization

Signature

function beginAuthSession(authUrl: string, authHeaders: () => Promise<Record<string, string>>): Promise<void>

Prerequisites

Implement a backend API endpoint that generates a public/private key JWT, with its payload structured as an UploadJwt, and its public key certificate added to your JWT Certificates.

Example

const upload = Upload({ apiKey: "free" }); // Replace "free" with your API key.
upload.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

Ends an authorized browser session, preventing the user from downloading further private files.

Signature

function endAuthSession(): Promise<void>

Prerequisites

Can only be called after a successful call to beginAuthSession.

Example

const upload = Upload({ apiKey: "free" }); // Replace "free" with your API key.

// User signs in:
upload.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

// User downloads files:
// ...

// User signs out:
upload.endAuthSession();