Replacebase

Replacebase is a TypeScript library that serves as a drop-in replacement for Supabase's backend. It wraps your Postgres database and S3 storage, and exposes a Supabase-compatible API. This means you don't have to change any frontend logic and can unify all your backend code for a simpler architecture.

When to Apply

• Setting up a new Replacebase instance to replace Supabase
• Migrating an existing app from Supabase to self-hosted infrastructure
• Configuring REST API, Auth, Storage, or Realtime to work with Replacebase
• Updating @supabase/supabase-js client config to point at Replacebase
• Choosing a hosting provider or framework integration for Replacebase

What Replacebase Supports

Installation

npm install @specific.dev/replacebase

Setup

1. Gather Supabase Details

You need the following from your Supabase project:

1. Postgres connection string — click "Connect" in the Supabase dashboard top bar
2. JWT Signing Key URL — go to Settings > JWT Keys > View key details > Discovery URL
3. Legacy JWT secret — go to Settings > JWT Keys > Legacy JWT Secret
4. S3 connection details (if using storage) — go to Storage > S3

2. Initialize Replacebase

// server.ts
import { createReplacebase } from "replacebase";

const replacebase = await createReplacebase({
  databaseUrl: process.env.DATABASE_URL!, // Supabase Postgres connection string
  jwksUrl: process.env.JWKS_URL!, // Supabase JWT Signing Key URL
  jwtSecret: process.env.JWT_SECRET!, // Supabase JWT secret
  // If using storage, pass Supabase S3 details
  storage: {
    s3: {
      endpoint: process.env.S3_ENDPOINT!,
      region: process.env.S3_REGION!,
      accessKeyId: process.env.S3_ACCESS_KEY_ID!,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
    },
  },
});

3. Serve with Your Framework

Replacebase is framework-agnostic. Pick whichever fits your stack:

Next.js:

Since Next.js catch-all routes are mounted under a subpath, use the basePath option so Replacebase matches routes correctly:

// app/api/[...path]/route.ts
const replacebase = await createReplacebase({
  // ...
  basePath: "/api",
});

export const GET = replacebase.fetch;
export const POST = replacebase.fetch;
export const PUT = replacebase.fetch;
export const PATCH = replacebase.fetch;
export const DELETE = replacebase.fetch;

Note: Next.js API routes don't support WebSockets, so Realtime won't work with this setup. If you need Realtime, run Replacebase as a separate backend service.

Express:

import express from "express";

const app = express();
app.all("/*", replacebase.toNodeHandler());
const server = app.listen(3000);
replacebase.injectWebSocket(server); // Enables Realtime (broadcast + presence)

Hono / Bun / Deno / Cloudflare Workers (standard fetch):

export default { fetch: replacebase.fetch };

For Realtime support on Node.js, use @hono/node-server to get an HTTP server you can inject WebSockets into:

import { serve } from "@hono/node-server";

const server = serve({ fetch: replacebase.fetch, port: 3000 });
replacebase.injectWebSocket(server);

4. Update Client Config

The only frontend change is pointing the Supabase client at your Replacebase server:

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  "https://your-replacebase-server.com", // Your Replacebase URL
  "your-anon-key",
);

Configuration Reference

Exported API

Migration Path

Once Replacebase is running, you can gradually:

1. Change Postgres provider — move to AWS RDS, Neon, or any Postgres host. Update databaseUrl and your frontend keeps working.
2. Change storage provider — switch to AWS S3, Cloudflare R2, or any S3-compatible service. Migrate files with rclone and update credentials.
3. Migrate away from the Supabase SDK — build regular backend endpoints alongside Replacebase. Replace supabase.from("posts").select() calls with your own API. Eventually drop @supabase/supabase-js entirely.