Basic Usage

Upload, retrieve, and delete files with Better Media.

This page walks through the core operations — upload, retrieve, and delete — using a minimal local setup. For a full production setup see Installation.

Setup

lib/media.ts

import { createBetterMedia } from "@better-media/framework";
import { FileSystemStorageAdapter } from "@better-media/adapter-storage-filesystem";
import { memoryDatabase } from "@better-media/adapter-db-memory";

export const media = createBetterMedia({
  storage: new FileSystemStorageAdapter({ baseDir: "./uploads" }),
  database: memoryDatabase(),
  plugins: [],
});

Upload a file

Pass a Buffer, stream, file path, or URL to media.upload.ingest():

const result = await media.upload.ingest({
  file: { buffer: fileBuffer },
  metadata: {
    filename: "photo.jpg",
    mimeType: "image/jpeg",
  },
});

The result contains everything you need to reference the file later:

{
  id: "01J8XKPZ...",        // database record ID — use this to reference the file
  key: "uploads/photo.jpg", // storage key
  status: "processed",      // "stored" | "processed"
  metadata: { filename: "photo.jpg", mimeType: "image/jpeg" }
}

Save result.id — it's the identifier for all subsequent operations.

Retrieve a file

Get the raw file bytes by record ID:

const file = await media.files.get(result.id);
// returns Buffer | null

Get a URL to serve the file (requires an adapter that supports URLs, e.g. S3):

const url = await media.files.getUrl(result.id, { expiresIn: 3600 });
// returns a signed URL valid for 1 hour

Check if a file exists:

const exists = await media.files.exists(result.id);
// returns true | false

Delete a file

Removes the file from storage and the database record:

await media.files.delete(result.id);

Handle errors

Wrap upload calls in a try/catch to handle validation failures and infrastructure errors:

import { ValidationError } from "@better-media/framework";

try {
  const result = await media.upload.ingest({
    file: { buffer: fileBuffer },
    metadata: { filename: "photo.jpg", mimeType: "image/jpeg" },
  });
} catch (err) {
  if (err instanceof ValidationError) {
    // File was rejected by a sync plugin (wrong type, too large, virus detected, etc.)
    console.error(err.message);
  } else {
    // Storage failure, DB connection error, etc.
    throw err;
  }
}