npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

octoload

v0.3.1

Published

Browser-to-S3/R2 image uploads with PostgreSQL or SQLite metadata and framework scaffolds

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.ts

The 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:docs

CI 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.

MIT license.

CI maintenance

GitHub Actions maintenance covers workflows, parallel checks, action versions, and weekly updates.