Storage

Aphex uses a pluggable storage system for file uploads. By default it writes to the local filesystem so you can develop without setting anything up. For production you'll usually swap to S3, R2, or another S3-compatible backend.

Quick setup

The base template's src/lib/server/storage/index.ts picks an adapter at boot from environment variables:

import { s3Storage } from '@aphexcms/storage-s3';
import { createStorageAdapter } from '@aphexcms/cms-core/server';
import { env } from '$env/dynamic/private';

let storageAdapter;

if (env.R2_BUCKET && env.R2_ENDPOINT && env.R2_ACCESS_KEY_ID && env.R2_SECRET_ACCESS_KEY) {
	storageAdapter = s3Storage({
		bucket: env.R2_BUCKET,
		endpoint: env.R2_ENDPOINT,
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
		publicUrl: env.R2_PUBLIC_URL || ''
	}).adapter;
} else {
	storageAdapter = createStorageAdapter('local', {
		basePath: './static/uploads',
		baseUrl: '/uploads'
	});
}

export { storageAdapter };

R2_BUCKET=my-bucket
R2_ENDPOINT=https://<account>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_PUBLIC_URL=https://cdn.your-app.com

Default local adapter

When you omit the storage option from createCMSConfig entirely, Aphex spins up its own local adapter — different from the template's:

If you want the access-controlled /media/... serving without the template's pass-through, just delete the conditional in src/lib/server/storage/index.ts and don't set storage on the config at all.

Switching to S3

pnpm add @aphexcms/storage-s3

s3Storage() returns { adapter, disableLocalStorage: true } so you can plug it straight into the config:

import { s3Storage } from '@aphexcms/storage-s3';
import { env } from '$env/dynamic/private';

const storage = s3Storage({
	bucket: env.R2_BUCKET,
	endpoint: env.R2_ENDPOINT,
	accessKeyId: env.R2_ACCESS_KEY_ID,
	secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	publicUrl: env.R2_PUBLIC_URL
});

export default createCMSConfig({
	storage
	// ...
});

Options

Provider snippets

s3Storage({
	bucket: env.R2_BUCKET,
	endpoint: env.R2_ENDPOINT, // https://<account>.r2.cloudflarestorage.com
	accessKeyId: env.R2_ACCESS_KEY_ID,
	secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	publicUrl: env.R2_PUBLIC_URL // your cdn / public bucket URL
});

s3Storage({
	bucket: 'my-bucket',
	endpoint: 'https://s3.us-east-1.amazonaws.com',
	accessKeyId: env.AWS_ACCESS_KEY_ID,
	secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
	region: 'us-east-1'
});

s3Storage({
	bucket: 'my-bucket',
	endpoint: 'http://localhost:9000',
	accessKeyId: 'minioadmin',
	secretAccessKey: 'minioadmin'
});

Upload flow

When a file is uploaded via the admin UI or POST /api/assets:

Image metadata

Sharp extracts the following on image upload:

Stored in the asset's metadata JSONB column.

Asset access control

Assets served through the CDN route /media/[id]/[filename] go through the same auth + capability stack as documents:

• Public assets — served without authentication.
• Private assets — fields marked private: true in your schema require an authenticated session, or a signed URL.
• Organization isolation — assets respect the same multi-tenant rules as documents. Parent orgs can read child org assets.

Every asset is proxied through this route by default, including S3 and R2 ones — the bytes are read with the adapter's getObject and streamed back, so the checks above actually decide whether the caller gets the file.

Proxying costs a round-trip through your app for every byte, which is the wrong trade for large files — a 200 MB video download shouldn't occupy a server process. Opt those out with a predicate:

export default createCMSConfig({
	signedDownloads: {
		// Access checks still run first: a signed URL is only ever minted for a
		// request that was already allowed to read the file.
		shouldUseSignedURL: (asset) => asset.size > 25 * 1024 * 1024,
		expiresIn: 900 // seconds, default 15 minutes
	}
});

Requires getSignedUrl on the adapter. Without it the route proxies anyway rather than failing — serving the file correctly beats refusing to serve it.

Private assets

Mark a field private: true and any asset uploaded into it requires authorization to read:

{ name: 'contract', type: 'file', private: true }
{ name: 'proofSheet', type: 'image', private: true }

Both image and file fields support it. A request for a private asset without authorization gets 401; with a session belonging to another organization, 403. Private responses are always sent Cache-Control: private, no-store, so they never land in a shared cache.

Signed URLs

A session is the wrong mechanism for a public-facing page: an <img>, a <video>, or a link in an email carries no admin cookie. A signed URL grants one asset for a bounded window, so your app can decide who may see a file and then hand them a link that proves it.

Set a secret:

export default createCMSConfig({
	security: {
		// Long and random; keep it out of source and stable across deploys.
		assetSigningSecret: env.APHEX_ASSET_SIGNING_SECRET
	}
});

Then mint links server-side, where the secret lives — a load function, an API route, an email renderer:

import { signAssetUrl } from '@aphexcms/cms-core/server';

export async function load({ locals }) {
	const contract = await getContractFor(locals.user);

	return {
		// Valid for one hour, for this asset only.
		url: signAssetUrl(
			locals.aphexCMS.config.security?.assetSigningSecret,
			`/media/${contract.assetId}/${contract.filename}`,
			contract.assetId,
			{ expiresIn: 3600 }
		)
	};
}

The result is an ordinary URL on your own domain:

/media/b3f1c0de-…/contract.pdf?exp=1736450000&sig=8Qb2…

Everything still runs through the media route, so range requests, image derivatives and access checks all behave exactly as they do for any other asset. The bucket stays private and its key layout stays invisible — unlike signedDownloads above, which redirects the viewer to a URL on the storage provider.

What the signature covers. The asset id and the expiry, and nothing else. Not the filename, which is cosmetic and would make a rename break live links. Not the requested width either — a responsive srcset asks for the same image at several widths, so binding the width would mean a signature per breakpoint. A signature answers "may this caller read this asset", not "which rendition"; every derivative is the same picture, and the access decision is identical for all of them.

Failure is closed. With no assetSigningSecret configured, signAssetUrl returns the URL unchanged and verification always fails — so a misconfiguration costs access rather than granting it. Expired, tampered and mismatched signatures are all rejected identically, without saying why.

Adapter tracking and migrations

Each asset row stores which storageAdapter was used (e.g. 'local' or 's3'). This enables:

• Safe migrations — move from local to S3 without breaking existing assets. Old files keep working through the local adapter while new ones flow into S3.
• Adapter mismatch warnings — deleting an asset stored by a different adapter logs a warning rather than silently dropping the row.
• Mixed storage — older assets on local storage continue to work after switching backends.

Custom adapters

Implement the StorageAdapter interface and pass the result to createCMSConfig({ storage }). Most users will never need to do this — start with the S3 helper unless you're integrating an unusual backend.

interface StorageAdapter {
	readonly name: string;

	// Core operations (required)
	store(data: UploadFileData): Promise<StorageFile>;
	delete(path: string): Promise<boolean>;
	exists(path: string): Promise<boolean>;
	getUrl(path: string): string;
	// Required: `/media/:id/:filename` proxies every asset through this, which is
	// what makes its access checks real. An adapter that can't read its own
	// objects back can't serve them.
	getObject(path: string): Promise<Buffer>;

	// Info and health
	getStorageInfo(): Promise<{ totalSize: number; availableSpace?: number }>;
	isHealthy(): Promise<boolean>;

	// Connection lifecycle (optional)
	connect?(): Promise<void>;
	disconnect?(): Promise<void>;

	// Extended operations (optional — enable admin browsing, signed URLs)
	listObjects?(options?: ListObjectsOptions): Promise<ListObjectsResult>;
	copyObject?(sourcePath: string, destPath: string): Promise<boolean>;
	getObjectMetadata?(path: string): Promise<StorageObjectMetadata>;
	getSignedUrl?(path: string, expiresIn?: number): Promise<string>;
	// Adopt the app's `upload.maxFileSize`, so the limit has a single home.
	setMaxFileSize?(bytes: number): void;
}

The name field identifies which adapter stored each file in cms_assets.storageAdapter, so it must be unique per backend. The required methods give you upload, delete, exists, URL generation and serving; the optional ones unlock in-app file browsing, pre-signed URLs, and full variant cleanup on delete.

Two optional methods are worth implementing even though nothing breaks without them:

• listObjects — deleting an asset sweeps everything under its {assetId}/ key prefix, which is how derivatives generated under a previous image config get cleaned up. The variant record is replaced wholesale when the config hash changes, so the database has no memory of those files; a prefix listing is the only thing that can still find them. Without it, deletion falls back to the recorded variants and older ones are orphaned in the bucket.
• setMaxFileSize — lets upload.maxFileSize be the single place the limit is set. Without it your adapter keeps its own constructor value, and the two can disagree.

See also