Railway Buckets

Documentation from leoisadev1/convex-railway-buckets, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

Railway Buckets for Convex

A Convex component that stores files in Railway Buckets. Browsers upload straight to the bucket through presigned URLs, and Convex keeps the metadata, so queries over your files are reactive and paginated.

Railway Buckets cost $0.015 per GB-month, with free API calls and free egress from the bucket.

Copy code// React: upload a file, get back its metadata once it is stored and verified.
const upload = useUploadFile(api.files);
const file = await upload(input.files[0], { onProgress: setProgress });

What you get:

• Direct browser uploads with progress, no file bytes passing through Convex.
• Limits the bucket enforces. Each upload URL is signed for one exact size and content type, and only writes if nothing is at the key yet. Railway rejects any other body, and a replayed URL can't overwrite the file.
• Uploads tied to the uploader. Only the identity that asked for an upload URL can confirm the upload.
• An onUpload hook that runs in the same transaction that records the file, so linking a file to your own tables is atomic.
• Durable cleanup. Abandoned uploads get deleted, and deletes retry until the bucket confirms them.
• No AWS SDK. A small SigV4 signer on Web Crypto runs in queries, mutations, actions, and HTTP actions.
• Credentials stay in the component. They are bound as component env vars and never travel in function arguments, scheduled jobs, or tables.

Requires convex 1.39 or newer, for component env vars.

Quick start

You'll end up with a React page that uploads files to your bucket and lists them. The example app is the finished version.

1. Install

Copy codenpm install convex-railway-buckets

2. Create a bucket and give Convex its credentials

Create a bucket in the Railway dashboard, or with the CLI:

Copy coderailway bucket create my-uploads -r sjc

Pipe its credentials into the setup command. It sets three env vars on your Convex deployment, passing values over stdin so the secret key never shows up in your shell history or process list:

Copy coderailway bucket credentials -b my-uploads --json | npx convex-railway-buckets env

Add --prod (or any other convex env set flag) to target another deployment.

Browsers need CORS to upload to the bucket. Allow every origin your app runs on. The command replaces the previous policy, so list them all each time:

Copy coderailway bucket credentials -b my-uploads --json \
  | npx convex-railway-buckets cors --origin http://localhost:5173 --origin https://myapp.com

3. Install the component

Declare the env vars in convex/convex.config.ts and bind them to the component:

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import railwayBuckets from "convex-railway-buckets/convex.config.js";

const app = defineApp({
  env: {
    RAILWAY_BUCKET: v.string(),
    RAILWAY_BUCKET_ACCESS_KEY_ID: v.string(),
    RAILWAY_BUCKET_SECRET_ACCESS_KEY: v.string(),
  },
});

app.use(railwayBuckets, {
  env: {
    BUCKET: app.env.RAILWAY_BUCKET,
    ACCESS_KEY_ID: app.env.RAILWAY_BUCKET_ACCESS_KEY_ID,
    SECRET_ACCESS_KEY: app.env.RAILWAY_BUCKET_SECRET_ACCESS_KEY,
  },
});

export default app;

Convex refuses to deploy if any of the three env vars is missing, so a typo shows up at npx convex dev instead of at the first upload.

4. Expose upload functions and call them from React

Copy code// convex/files.ts
import { RailwayBuckets } from "convex-railway-buckets";
import { components } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

export const buckets = new RailwayBuckets(components.railwayBuckets, {
  upload: {
    maxSize: 10 * 1024 * 1024,
    allowedContentTypes: ["image/*"],
    keyPrefix: "uploads/",
  },
});

export const { generateUploadUrl, verifyUpload, completeUpload, cancelUpload } =
  buckets.clientApi<DataModel>({
    checkUpload: async (ctx) => {
      if (!(await ctx.auth.getUserIdentity())) throw new Error("Sign in first");
    },
    onUpload: async (ctx, file) => {
      await ctx.db.insert("photos", { key: file.key, owner: file.owner });
    },
  });

Copy code// src/Upload.tsx
import { useUploadFile } from "convex-railway-buckets/react";
import { api } from "../convex/_generated/api";

export function Upload() {
  const upload = useUploadFile(api.files);
  return (
    <input
      type="file"
      onChange={async (event) => {
        const file = event.target.files?.[0];
        if (file) console.log("stored", await upload(file));
      }}
    />
  );
}

Choose an image. The promise resolves once the file is in the bucket, verified, and recorded, and by then onUpload has inserted your photos row.

How an upload works

browser                      your Convex functions                Railway
   │ generateUploadUrl({size, type}) ─▶ checkUpload, policy
   │                                    component signs a PUT for
   │ ◀──────── { key, url, headers }    exactly size + type, once
   │ PUT url  (headers) ──────────────────────────────────────────▶ 200
   │ verifyUpload({key}) ─────────────▶ HEAD the object ──────────▶ 200
   │ completeUpload({key}) ───────────▶ files row + onUpload,
   │ ◀──────────────────── file          one transaction

Each step checks that the caller is the same owner who requested the URL. The owner defaults to the caller's tokenIdentifier, or null when signed out. Override it with getOwner.

If the client never finishes, the upload expires: after the URL's lifetime plus completeWithin (6 hours by default), the component drops it and deletes anything that was uploaded. completeUpload is safe to retry. A second call by the same owner returns the same file and doesn't run onUpload again.

Every upload URL also signs a random x-amz-meta-upload-id. Cleanup only deletes an object carrying the ID of the upload being cleaned up, pinned to that exact version with If-Match, so an abandoned upload can never take out an unrelated object that happens to share its key.

Guides

Show files

getFile and listFiles return metadata plus a presigned GET URL. Railway buckets are always private, so every read goes through a URL like this.

Copy codeexport const { getFile, listFiles } = buckets.clientApi<DataModel>({
  checkRead: async (ctx, file) => {
    const identity = await ctx.auth.getUserIdentity();
    if (file.owner !== identity?.tokenIdentifier) throw new Error("Not yours");
  },
  checkList: async (ctx) => {
    if (!(await ctx.auth.getUserIdentity())) throw new Error("Sign in first");
  },
});

From your own queries, call buckets.getFile(ctx, key), buckets.listFiles(ctx, { paginationOpts, prefix }), or buckets.getUrl(ctx, key, options). listFiles returns the standard pagination shape. Use usePaginatedQuery from convex-helpers/react on the client, since the component paginates with the convex-helpers paginator.

URLs last an hour by default (urlExpiresIn option, up to 7 days). A query's result is cached and pushed to subscribers until its data changes, so a page left open longer than the expiry can end up holding dead URLs. For long-lived pages, raise the expiry or use the stable route below. In actions, buckets.getFreshUrl(ctx, key) always signs a new URL.

To make the browser download instead of display, pass { disposition: "attachment" }. The download uses the original filename.

Serve files at stable URLs

registerRoutes adds an HTTP route that redirects to a fresh presigned URL, so an <img src> never expires:

Copy code// convex/http.ts
import { httpRouter } from "convex/server";
import { buckets } from "./files";

const http = httpRouter();
buckets.registerRoutes(http, {
  pathPrefix: "/files/",
  authorize: async (ctx, request, file) => true,
});
export default http;

GET https://<deployment>.convex.site/files/<key> now responds with a 302 to a URL signed for that request (never a cached one). Browsers don't send Convex auth tokens on <img> requests, so authorize can only check what's in the request itself, such as a cookie or a signed query parameter. () => true means anyone who knows the key can read the file. Generated keys are random UUIDs.

Delete files

Copy codeexport const { deleteFile } = buckets.clientApi<DataModel>({
  checkDelete: async (ctx, key, file) => {
    /* throw to refuse */
  },
  onDelete: async (ctx, key, file) => {
    /* remove your rows for this key */
  },
});

Or call buckets.deleteFile(ctx, key) from any mutation or action. Convex forgets the file right away, and the component deletes the object in the background, retrying with backoff (capped at one hour) until Railway confirms.

The key stays reserved while the delete is pending, so a new file can't land on it and get hit by it. For browser uploads the reservation lasts until the original upload URL's deadline (URL lifetime plus completeWithin), when the component checks the key one last time. That catches a client that replays its old URL after the delete. Generated keys are random, so this only matters if you reuse custom keys. Files stored with store() skip the wait because their URL never leaves your server.

Store files from the server

Copy codeexport const saveReport = action({
  args: {},
  handler: async (ctx) => {
    const csv = await buildCsv();
    const file = await buckets.store(ctx, csv, {
      contentType: "text/csv",
      filename: "report.csv",
      keyPrefix: "reports/",
    });
    return file.key;
  },
});

store accepts a Blob, ArrayBuffer, Uint8Array, or string. It skips the upload policy (server code is trusted) and refuses to overwrite: if key is already in use, even by an object Convex doesn't know about, it throws KEY_IN_USE and leaves the existing object alone. To read bytes back in an action, use buckets.download(ctx, key), which returns a Response.

Adopt objects written elsewhere

If another Railway service writes to the bucket, record its objects with buckets.syncFile(ctx, key) from an action. It HEADs the object and upserts the record. When the object is gone, it removes the record and returns null.

Upload without React

convex-railway-buckets/browser exports uploadFile, which takes any ConvexClient, ConvexReactClient, or ConvexHttpClient. Use it with Svelte, Vue, or plain JS. It has no React dependency:

Copy codeimport { uploadFile } from "convex-railway-buckets/browser";

const file = await uploadFile(client, api.files, blob, {
  onProgress: ({ loaded, total }) => console.log(loaded / total),
  signal: abortController.signal,
});

Aborting or failing the PUT calls cancelUpload when you've exported it.

Test with convex-test

Copy codeimport { convexTest } from "convex-test";
import railwayBuckets from "convex-railway-buckets/test";

const t = convexTest(schema, modules);
railwayBuckets.register(t);

Bucket requests still go through fetch, so stub it in tests that upload, verify, or delete.

Use more than one bucket

Install the component once per bucket under different names, and bind each instance's env vars:

Copy codeapp.use(railwayBuckets, {
  name: "avatars",
  env: { BUCKET: app.env.AVATARS_BUCKET /* ... */ },
});
app.use(railwayBuckets, {
  name: "exports",
  env: { BUCKET: app.env.EXPORTS_BUCKET /* ... */ },
});

Then create new RailwayBuckets(components.avatars) and new RailwayBuckets(components.exports).

Reference

Component env vars

new RailwayBuckets(component, options?)

Methods (ctx is any context that can run the needed function type):

A file is { key, size, contentType, etag, lastModified, filename?, owner }. fileValidator and fileWithUrlValidator are exported for your own returns validators.

clientApi(options)

Returns generateUploadUrl, verifyUpload, completeUpload, cancelUpload, getFile, listFiles, and deleteFile. Export the ones you need.

A missing check denies its function, so exporting a function doesn't make it public by accident.

Errors

Failures throw ConvexError<{ code, message }>. Branch on error.data.code:

Admin queries

components.railwayBuckets.admin.pendingUploads and admin.pendingDeletions list in-flight work. A deletion whose attempt keeps climbing with a lastError usually means the credentials are wrong or were rotated. A deletion with a nextAttemptAt hours away is waiting for its final recheck, which is expected. Run them from the dashboard or with npx convex run --component railwayBuckets admin:pendingDeletions.

Security notes

• Content types are declared, not sniffed. The bucket enforces the Content-Type header the client declared, not what the bytes are. Someone can upload HTML labeled image/png, and image/* includes SVG, which can contain script. Files are served from Railway's storage domain, never your app's origin, so they can't read your cookies. If you render user files inline, prefer an explicit list like ["image/png", "image/jpeg"], or serve risky types with disposition: "attachment".
• Presigned URLs are bearer tokens until they expire. Anyone holding one can read that object. Keep read expiries as short as your UI allows.
• The access key ID appears in every presigned URL. That's how SigV4 works and it isn't secret. The secret key never leaves the component.

Limitations

• Single-PUT uploads only, up to 5 GiB. Multipart uploads aren't supported yet.
• Keys are immutable. To replace a file, upload a new one and delete the old one.
• Railway buckets don't support versioning, lifecycle rules, or server-side encryption settings (objects are encrypted at rest).
• There's no bulk import of existing bucket contents yet. Use syncFile per key.

Developing this package

Copy codenpm install
CONVEX_AGENT_MODE=anonymous npx convex dev   # local backend with the example app
npm run dev:frontend                          # example UI on :5173
npm test                                      # unit and type tests
npm run test:e2e                              # against a real bucket, needs convex dev running

DESIGN.md records the design decisions and what was verified against a live bucket.