Protocol v0.3.0

Media handling
shouldn't be this hard.

Upload, transform, and serve files with a clean API and pluggable adapters for any storage or database.

Get StartedView Documentation
Supports
S3_STORAGE
FILESYSTEM
POSTGRES_MONGO
core/config.ts
01
import { createBetterMedia } from "@better-media/framework";
02
import { memoryStorage } from "@better-media/adapter-storage-memory";
03
import { memoryDatabase } from "@better-media/adapter-db-memory";
04
import { validationPlugin } from "@better-media/plugin-validation";
05
06
export const media = createBetterMedia({
07
storage: memoryStorage(),
08
database: memoryDatabase(),
09
plugins: [
10
validationPlugin({
11
allowedMimeTypes: ["image/jpeg", "image/png"],
12
maxBytes: 10 * 1024 * 1024,
13
}),
14
],
15
});
$npm i @better-media/framework
Quick Start

Get started in minutes.

Install the package, define your media config, and ship your first upload with a single runtime.

01

Install

Add Better Media, then bring in the adapters and plugins your app needs.

npm i @better-media/framework
02

Configure

Create a small media config that defines your storage, database, and plugins.

media.config.ts
03

First Upload

Ingest your first file through one upload API and let the pipeline do the rest.

await media.upload.ingest({...})
Features

Built for production media flows.

One upload pipeline with strong defaults, portable adapters, and operational features that fit real applications.

cloud_sync
storage

Agnostic Storage Layer

The same API for S3, Azure Blob, GCS, or Local FS. Change your provider in production with zero code changes to your application logic.

ADAPTERS_READYS3_COMPATIBLE
shield_check

Safe by Default

Automatic Magic Number validation for MIME types. Stream-based processing ensures huge files never crash your server instance.

bolt

Runtime Optimized

Zero-dependency core. Ultra-small bundle footprint. Built on the fastest streaming primitives available in Node.js and Deno.

key

Presigned Everything

Handle multi-gigabyte uploads without touching your server. Secure, time-limited presigned URLs with one function call.

Frameworks

Framework Agnostic Support

Better Media is built to work across the most popular Node.js frameworks and beyond. Whether you're building APIs, microservices, or full-stack applications, integration is simple and consistent.

→import { createMedia } from "better-media";
code
Express.js
api
NestJS
bolt
Fastify
water_drop
Koa
hexagon
Hapi
layers
Next.js
bakery_dining
Bun
rainy
Deno
and more...
Architecture

Unified architecture.

Core defines contracts. Adapters implement infrastructure. The framework orchestrates the upload lifecycle around one consistent model.

settings_input_component

Better Media Core

Contracts and lifecycle primitives for uploads, validation, processing, and persistence.

Core ContractsAdapter DrivenPlugin Ready
database

Database Adapters

PostgreSQL, MongoDB, SQLite, and schema tooling.

cloud

Storage Adapters

S3, Cloudflare R2, Google GCS, filesystem, or memory.

extension

Official Plugins

Validation, virus scanning, and media processing hooks.

Foundation

Bring your own stack.

Better Media doesn't lock you into a provider. Mix and match databases and storage backends with zero code changes.

Adapter DrivenProduction Ready
database

Databases

Structured metadata

databasePostgreSQL
schemaMongoDB
data_objectSQLite
cloud

Storage Adapters

Object storage backends

cloud_uploadAWS S3
speedCloudflare R2
folder_managedGoogle GCS
Plugins

Official plugins.

Extend functionality without writing boilerplate. Plug in validation, scanning, and media processing on the same upload lifecycle.

View Pluginsarrow_forward
verified_user

@better-media/plugin-validation

Strict MIME validation, size checks, and upload policy enforcement.

npm i @better-media/plugin-validation
security

@better-media/plugin-virus-scan

ClamAV-powered scanning to stop unsafe files before they reach storage.

npm i @better-media/plugin-virus-scan
image

@better-media/plugin-media-processing

Resize, optimize, and prepare media assets as part of the upload lifecycle.

npm i @better-media/plugin-media-processing

Better together.

Better Media is powered by contributors from all over the world.

Contributor
★ 4 Stars