octoload
v0.3.1
Published
Browser-to-S3/R2 image uploads with PostgreSQL or SQLite metadata and framework scaffolds
Maintainers
Readme
Octoload
Upload images straight from your browser to Amazon S3 or Cloudflare R2. Octoload connects a lightweight browser client to your app’s authentication, PostgreSQL or SQLite metadata, and framework handlers. You own the storage and the data.
This checkout is the unpublished 0.3.1 source candidate. npm latest is
0.2.1. The historical 0.3.0 GitHub prerelease
and its tarball represent an earlier commit, not this candidate. See the
upgrade notes before upgrading from npm 0.2.1.
Install
Use Node.js 24+. Bun is optional. Choose PostgreSQL or SQLite for metadata.
To try a locally built 0.3.1 candidate tarball in an existing Next.js app with PostgreSQL, Drizzle, and Better Auth:
pnpm add /path/to/octoload-0.3.1.tgz drizzle-orm pg
pnpm add -D drizzle-kit @types/pg
pnpm exec octoload init --framework nextjs --adapter s3 --auth better-auth
pnpm exec octoload generate --output src/db/upload-schema.tsThe scaffold creates authenticated upload and image routes. Connect your database,
fill in the server environment, and apply the generated schema using the
Next.js setup guide. init preserves existing files;
generate replaces its output file.
pnpm exec octoload migrate generates and applies tracked Drizzle migrations;
--generate-only generates SQL offline for review. Existing installations should
apply the new lookup indexes using the database upgrade guide.
For SQLite, use --dialect sqlite with both init and generate.
See the database guide
for SQLite and PGlite connections, init --driver pglite, and runnable examples.
Upload an image
With the routes configured, add this Next.js client component:
'use client';
import { useState } from 'react';
import { OctoloadClient } from 'octoload/client';
export function PhotoUpload() {
const [status, setStatus] = useState('');
async function upload(file: File) {
const client = new OctoloadClient({ baseUrl: window.location.origin });
try {
const { image } = await client.uploadFile(file, {
alt: file.name,
onProgress: ({ percentage }) => setStatus(`Uploading ${percentage}%`),
});
const { url } = await client.getImage(image.id);
setStatus(`Uploaded: ${url}`);
} catch (error) {
setStatus(error instanceof Error ? error.message : 'Upload failed');
}
}
return (
<>
<input
type="file"
accept="image/jpeg,image/png,image/webp"
onChange={(event) => {
const file = event.currentTarget.files?.[0];
if (file) void upload(file);
}}
/>
<p>{status}</p>
</>
);
}Uploads are private by default. The client asks your app for a signed URL, PUTs the file directly to the bucket, then finalizes the upload. Your app checks stored size and content type before marking the image ready. Private reads use signed GET URLs; private reads and all deletes enforce ownership through your app’s session. Public reads omit internal metadata unless the reader is the image owner. Deletion erases current object bytes but retains an empty replay-blocking tombstone; see retired keys and metadata request limits.
uploadMultiple(files) uploads in batches of three. If a batch fails,
UploadBatchError.outcomes preserves successful results, individual errors, and
files not yet started. Use onEvent for timed
phase events, onError for structured failures, and recoverUpload to reconcile
an uncertain upload without sending the file again. See
observability and recovery,
including the new timeout defaults and upgrade notes.
Server policy and lifecycle hooks are awaited; see server lifecycle hooks for authorization, deletion vetoes, and post-finalize behavior.
Configure your app
Export your database from src/db/index.ts:
import { drizzle } from 'drizzle-orm/node-postgres';
export const db = drizzle(process.env.DATABASE_URL!);Include the generated upload schema in your Drizzle configuration:
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
schema: ['./src/db/schema.ts', './src/db/upload-schema.ts'],
out: './migrations',
dialect: 'postgresql',
dbCredentials: { url: process.env.DATABASE_URL! },
});The generated Next.js presign route uses:
import { createPresignHandler } from 'octoload/nextjs';
import { uploadHandlerOptions } from '../../../../lib/octoload/server';
export const POST = createPresignHandler({
...uploadHandlerOptions,
requireAuth: true,
});Allow browser PUT requests in your bucket’s CORS configuration. Replace the origin with yours and add your local development origin if needed:
[
{
"AllowedOrigins": ["https://app.example.com"],
"AllowedMethods": ["PUT"],
"AllowedHeaders": ["Content-Type", "If-None-Match"]
}
]The setup guide covers environment variables, migrations, and session wiring. Other guides cover Cloudflare R2, React Router, and scheduled cleanup.
The scaffold allows JPEG, PNG, WebP, and GIF up to 10 MiB. The core flow supports
single PUT uploads and checks object metadata. To keep uploads lightweight,
Octoload does not decode images: matching size and content type do not prove
that the bytes are a valid image. Keep uploads private and authenticated; apps
needing content validation can add it separately. Decoding is future work.
Browser checksum computation is disabled by default; calculateChecksum: true
adds unverified SHA-256 metadata. Checksum verification and server multipart workflows are not implemented. See
limits and access for
storage visibility and application authorization requirements.
Try a credential-free example
After building the checkout, run pnpm run example:presign. It uses dummy
credentials to show signed single-PUT headers for S3 and R2, without a bucket,
database, or network request. It is a signing example, not an end-to-end upload.
See the example.
Develop
Use Node 24+ and the pnpm version pinned in package.json:
pnpm install --frozen-lockfile
pnpm run test:docsCI runs type, lint, format, coverage, documentation, packed-package, and browser E2E checks.
The contribution guide lists the full verification command.
The storage harnesses check private R2 storage with Cloudflare
cf, and signed uploads and replay protection with dedicated S3/R2 credentials.
The browser suite runs without credentials against local HTTP storage, or against a dedicated R2 bucket with test credentials. See the testing guide for commands and verified boundaries.
CI maintenance
GitHub Actions maintenance covers workflows, parallel checks, action versions, and weekly updates.
