Node.js SDK

The medialit package calls the MediaLit API with your app's API key. It runs on the server only and refuses to start in a browser.

npm install medialit

Node.js 18 or later is required.

new MediaLit()

import { MediaLit } from "medialit";

const medialit = new MediaLit({
    apiKey: process.env.MEDIALIT_API_KEY,
    endpoint: process.env.MEDIALIT_ENDPOINT,
});

Every method throws an Error with MediaLit's message when a request fails.

upload

const media = await medialit.upload("./photo.jpg", {
    access: "public",
    caption: "Team photo",
});

Uploads a file path, a Buffer or a readable stream in one request. The file is temporary until you seal it.

seal

const media = await medialit.seal(mediaId);

Keeps a temporary upload. Returns the media with its final file URL, which changes for public files. Sealing a file that is already sealed returns it unchanged.

get

const media = await medialit.get(mediaId);

Returns one file, including temporary ones. Private files come with a new signed URL each time.

list

const media = await medialit.list(1, 20, { access: "public", group: "avatars" });

Returns a page of sealed files, newest first. The arguments are the page number, the page size and optional access and group filters.

delete

await medialit.delete(mediaId);

Deletes the file and its thumbnail.

getCount and getStats

const count = await medialit.getCount(); // sealed files
const { storage, maxStorage } = await medialit.getStats(); // bytes

getSettings and updateSettings

await medialit.updateSettings({ useWebP: true, webpOutputQuality: 80 });
const settings = await medialit.getSettings();

Image processing settings for the app. useWebP converts uploaded images to WebP, at a webpOutputQuality from 0 to 100.

getSignature

const signature = await medialit.getSignature({ group: "avatars" });

Creates an upload signature for a browser. Pass it to the browser together with medialit.endpoint. Files uploaded with it go into group when you pass one.

createSignatureHandler

Creates a POST route that returns { signature, endpoint } for @medialit/react and @medialit/uploader. It works with any framework that uses the Fetch API's Request and Response, such as Next.js, Hono, Remix and Bun. For Express, see Let browsers upload.

import { createSignatureHandler } from "medialit";

export const POST = createSignatureHandler({
    authorize: async (request) => {
        const user = await getUser(request); // your app's authentication
        return user ? { group: user.id } : false;
    },
});

If MediaLit refuses to create a signature, the route responds with 500 and { error }.