Superfunction (SPFN)

Take your AI-built app from prototype to production

📖 superfunction.xyz — docs, package guides, and a full-stack tutorial.

spfn create --mode full wires the baseline into one application — core (server,
database, routes, codegen, typed client), auth (sessions, social login,
authorization), i18n (translation catalogs), and ops (your own operations, run
from the terminal with spfn ops, instead of an admin dashboard). Everything else is
installed only when you reach for it.

What is SPFN?

SPFN (Superfunction) is a TypeScript full-stack framework for products built with AI
coding agents. A Next.js app handles the frontend; an SPFN backend — built on Hono,
PostgreSQL and Drizzle ORM — handles the server side, either as its own long-lived
process or as serverless functions on the same origin. Requests are validated with
TypeBox and reach the browser through a typed client, so a route's input and output
types are the same object on both sides.

What makes it different from a stack you assemble yourself is that the shape is fixed.
Every feature is one vertical slice with the same four parts in the same four places:
an entity, a repository, a route, and a router registration. Nothing is left for a
human or an agent to invent per feature. On top of that, the parts every product needs
— authentication, storage, notifications, CMS, i18n, background jobs, and an MCP server
for operating the app — ship as @spfn/* packages rather than being rebuilt each time.

The point is that the first version and the production version are the same application.
You scaffold something deployable and authenticated on day one, then keep changing it —
rather than building a prototype and rebuilding it once it stops holding.

Status — Beta (0.x). SPFN is in active development and runs in production for its
authors. The public API is stabilizing, but may still change between minor releases
before 1.0 — pin your versions and skim the CHANGELOG before
upgrading. Install from the @beta tag, e.g. npm i @spfn/core@beta.

Why does my AI coding agent write the same feature differently every time?

Because nothing tells it where things go. Ask for "add orders" twice and you get two
different shapes: business logic in a route handler one time, in a service the next;
queries inline here, in a helper there. Each answer is reasonable on its own. Together
they become a codebase nobody — human or agent — can hold in their head.

The name for this is architecture drift: the gap that opens between the structure a
codebase was supposed to have and the structure it actually has. Agents accelerate it
for three ordinary reasons — they answer your prompt rather than reading your whole
codebase, they copy whatever shape they happen to read, and they produce faster than
anyone reviews. The long version is here,
including the usual answers to it and why they are all detection after the fact.

This is the wall most AI-built apps hit. The prototype works. The tenth feature is
where it stops being changeable.

SPFN answers it by removing the choice. One feature is one vertical slice:

src/server/
  entities/order.ts        # the data shape
  repositories/order.ts    # persistence
  routes/orders.ts         # the validated API contract
  router.ts                # registration

The agent is not asked to design an architecture. It is asked to fill in a known one.
Type safety is one guardrail here, alongside runtime schemas, generated migrations,
explicit module boundaries, and a build that fails when the contract breaks.

Do I need SPFN, or is Next.js enough?

Next.js alone is enough if nobody signs in and nobody has to operate it — a marketing
site, a public tool, a dashboard over data that is already public.

Everything else meets two gates, in this order.

Gate 1 — accounts. Nothing ships until people can sign in. Sessions and their expiry.
A callback flow per social provider, and the redirect URLs that break on deploy. Email or
phone verification. Roles and permissions on every route. Account deletion and recovery.
Device and key management.

Gate 2 — operations. The day after you deploy, someone has to refund an order, look up
a user, publish a change, retry a failed job. That is a second application: an admin
dashboard with its own auth, its own screens, and its own maintenance — and it keeps
growing for as long as the product does.

Neither gate is your product. Both have a known correct shape. Getting the first one
subtly wrong is a security incident rather than a bug.

So the question is where your tokens go. Building with an agent puts an explicit price
on both gates — every prompt, every regeneration, every fix that follows. SPFN's answer is
that they should cost you close to nothing:
@spfn/auth clears the first, and the ops surface clears the second by
running your operations from the terminal you already have open, instead of a dashboard you
have to build. What is left is the part only you can write.

How is SPFN different from NestJS?

Both give you a structured TypeScript backend. They differ in how much they decide for
you and in what they assume about the frontend.

NestJS is the better fit when you need freedom in how the backend is organized, or when
the frontend is not Next.js. SPFN is the better fit when you want one decided shape that
a coding agent can follow without being told again each time.

tRPC solves a narrower problem — typed calls between a client and server — and leaves
structure, persistence, and auth to you.

How do I start a new SPFN project?

# Create a new project — full mode wires core, auth, i18n and ops together
npx spfn@beta create my-app --mode full
cd my-app

# Start PostgreSQL and Redis
docker compose up -d

# Start both sides
npm run spfn:dev

Backend: http://localhost:8790 · Frontend: http://localhost:3790

Use --mode bare for the core architecture only. For an existing Next.js app, use
npx spfn@beta init --mode full.

How do I define a type-safe API route?

// src/server/routes/users.ts
import { route } from '@spfn/core/route';
import { Type } from '@sinclair/typebox';

export const listUsers = route.get('/users')
    .input({
        query: Type.Object({
            limit: Type.Optional(Type.Number()),
        }),
    })
    .handler(async (c) => {
        const { query } = await c.data();
        return { users: [], limit: query.limit ?? 10 };
    });

export const getUser = route.get('/users/:id')
    .input({
        params: Type.Object({
            id: Type.String(),
        }),
    })
    .handler(async (c) => {
        const { params } = await c.data();
        return { id: params.id, name: 'John' };
    });

export const createUser = route.post('/users')
    .input({
        body: Type.Object({
            name: Type.String(),
            email: Type.String(),
        }),
    })
    .handler(async (c) => {
        const { body } = await c.data();
        return { id: '1', ...body };
    });

Register them in the router — this is the API contract:

// src/server/router.ts
import { defineRouter } from '@spfn/core/route';
import { listUsers, getUser, createUser } from './routes/users';

export const appRouter = defineRouter({
    listUsers,
    getUser,
    createUser,
});

export type AppRouter = typeof appRouter;

How does the typed client know my route types?

Through the AppRouter type, not through generated client code. The client is created
once and infers everything from that type:

// src/lib/api-client.ts
import { createApi } from '@spfn/core/nextjs';
import type { AppRouter } from '@/server/router';

export const api = createApi<AppRouter>();

Calls are fully typed, with no manual types anywhere:

// app/page.tsx
import { api } from '@/lib/api-client';

export default async function Page() {
    const { users } = await api.listUsers.call({ query: { limit: 10 } });
    const user = await api.getUser.call({ params: { id: '123' } });

    return <div>{users.length} users</div>;
}

One piece does need codegen: the RPC proxy that forwards browser calls to the SPFN
server resolves routes from a generated map. Run pnpm codegen after changing routes
and commit the output.

// src/app/api/rpc/[routeName]/route.ts
import { createRpcProxy } from '@spfn/core/nextjs/server';
import { routeMap } from '@/generated/route-map';   // generated by `pnpm codegen`

export const { GET, POST } = createRpcProxy({ routeMap });

Where does each file go?

src/
├── server/
│   ├── router.ts           # defineRouter — the API contract
│   ├── server.config.ts    # server configuration
│   ├── routes/             # route.get/post/... definitions
│   ├── entities/           # Drizzle database schemas
│   └── repositories/       # data access layer
├── generated/
│   └── route-map.ts        # produced by `pnpm codegen` — never hand-edit
├── lib/
│   └── api-client.ts       # createApi<AppRouter>() — typed client
└── app/
    ├── api/rpc/[routeName]/route.ts   # RPC proxy → SPFN server
    └── page.tsx            # Next.js pages

Generated files are output, not editing targets.

How do I point Claude Code, Cursor, or Copilot at this project?

Point it at CONTRIBUTING.md. That file is the contract an AI coding
agent is expected to follow here: what the repo is, the commands, the vertical-slice
pattern, and the hard rules (never hand-edit generated files, migrations come from the
schema).

One file answers to people and agents alike, so there is no second copy of the rules to
drift out of sync. Each package's own README.md carries the authoritative detail for
that package — an agent changing @spfn/auth reads packages/auth/README.md as well.

Pointing an agent at a file like this is worth more than a long prompt describing a new
architecture for every feature.

How do I add authentication?

npm i @spfn/auth@beta

// src/server/router.ts
import { defineRouter } from '@spfn/core/route';
import { authRouter, authenticate } from '@spfn/auth/server';

export const appRouter = defineRouter({
    // your routes...
})
.packages([authRouter])
.use([authenticate]);

That brings sessions, social login, and RBAC. See
packages/auth/README.md for the four wiring points and the
environment variables each provider needs.

Can I operate the app without building an admin dashboard?

Yes. Write the operations an operator is allowed to perform as ops routes, and run them
from the terminal — spfn ops reads them from the running app, so nothing is generated
or configured locally:

spfn ops list --app https://api.example.com   # what can this app do?
spfn ops call refundOrder --param id=42
spfn ops call listCustomers --describe        # what does it take?

Each command uses the same repositories and services as the product, with its own input
schema and authorization rule, and answers only to a scoped, revocable ops token. Do not
expose tables as generic CRUD — expose operations.

spfn create --mode full scaffolds this surface. To drive the same operations from an
agent instead of a terminal, add @spfn/mcp with
spfn add @spfn/mcp and expose them as MCP tools too.

Which packages exist, and what does each do?

In the default setup:

Install when you need them:

Every package has a deep-dive README in packages/. Exact versions live on
npm — install from the @beta tag.

How do I deploy this?

Two targets. Both ship from the same repository, versioned together.

Vercel — serverless, one origin, no container

spfn add vercel

That scaffolds src/app/api/backend/[[...route]]/route.ts (a hono/vercel adapter) and
vercel.json. The SPFN app mounts under /api/backend, so the Next.js frontend and the
backend live on a single Vercel origin — point SPFN_API_URL at
https://<deployment>/api/backend. It runs on the Node runtime, not edge, because SPFN
needs pg and native bcrypt. If you use the Vercel Supabase integration, the adapter
maps the injected POSTGRES_URL onto DATABASE_URL for you.

One caveat: the in-process job worker does not run on serverless. Enqueuing still works,
but nothing drains the queue — schedule a route that processes a batch (Vercel Cron), or
run jobs on an always-on target. Seed and RBAC provisioning move to a deploy-time step
instead of running per cold start.

Always-on — a long-lived process

spfn build && spfn start          # or the generated Docker files
docker compose -f docker-compose.production.yml up --build -d

Background jobs, WebSocket events, and the periodic database health-check all need this
path. See the deployment guide.

What do I need installed?

• Node.js >= 20.0.0 — @spfn/core runs on @hono/node-server 2, which requires it
• Next.js >= 16.2.11 — only if you use the Next.js integration
• PostgreSQL 14+
• Redis — only when the features you enable need it

Next.js 15 is not supported. Its fixes for CVE-2025-66478
and the Server Components denial of service landed separately on each minor line
(15.0.5, 15.1.9, 15.2.6, …), so no single range can express "patched" — the packages
require ^16.2.11 instead.

PostgreSQL 13 is the oldest release the code actually runs on: gen_random_uuid() is a
column default and moved into the server in 13. The floor is 14 because 13 stopped
receiving fixes in November 2025.

FAQ

I built a Next.js app with an AI agent. Can I add SPFN to it?
Yes. Run npx spfn@beta init --mode full in the existing project. It adds the server
directory, the RPC proxy route, Docker files, and the codegen config, and updates your
package.json.

My agent keeps inventing new folder structures. Does this actually fix that?
It removes the decision. There is one place for entities, repositories, routes and the
router, and CONTRIBUTING.md states it. An agent that reads the file has nothing left to
invent. It does not stop an agent from writing bad logic inside a slice — that is the
line between the drift this removes and the drift it does not, set out in
architecture drift.

Can I use SPFN without Next.js?
Yes. next is an optional peer dependency of @spfn/core, and the Next.js integration
is one module (@spfn/core/nextjs). The server runs on Hono on its own. You give up the
typed client and RPC proxy, which are the Next.js-side pieces.

Can I use Prisma instead of Drizzle?
No. drizzle-orm is a required peer dependency, and the repository layer is built on it.

Can I deploy to Vercel?
Yes — run spfn add vercel. See How do I deploy this? for what
it scaffolds and the one caveat about background jobs.

Do I have to use Docker?
No. Vercel is a first-class target and needs no Docker. Docker is the always-on path, and
docker compose up -d is the convenient way to get PostgreSQL and Redis locally —
pointing at your own PostgreSQL works too. PostgreSQL itself is not optional.

Do I need to run codegen after every change?
Only after changing routes, and after schema changes run pnpm db:generate. The typed
client needs no codegen — it infers from AppRouter.

I have never built a backend. Is SPFN too much?
It is built for the opposite case. spfn create --mode full hands you a working,
authenticated, deployable app before you write a line — you are not assembling sessions,
OAuth, migrations and a data layer yourself, and you are not choosing an architecture.
The shape is fixed and written down in CONTRIBUTING.md, so your coding agent fills it
in instead of asking you to design it.

What SPFN removes is the architecture and the solved problems. What it does not remove is
the infrastructure: you still need a PostgreSQL database, and a setup step with real
environment variables in it. Knowing TypeScript helps, but the agent writes most of it.

What database does SPFN require?
PostgreSQL 14 or later. Redis is optional and only needed by some features.

Documentation

• superfunction.xyz — the documentation site
• Architecture drift — the problem this framework is shaped around, and where fixing the shape stops helping
• Prototype to Production — the whole loop, scaffold to MCP operations
• Full-stack tutorial — from spfn create to auth-guarded pages
• Examples — a step-by-step ladder, start at 01-minimal-api
• CONTRIBUTING.md — setup, the SPFN pattern, the hard rules, and the contract for AI coding agents

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, the
development workflow, the PR checklist, and the rules an AI coding agent is expected to
follow. By participating you agree to our Code of Conduct.

Found a security issue? Please report it privately — see SECURITY.md.

License

MIT © FXY Inc.