The spfn CLI scaffolds and runs a Hono-based backend that lives inside
your Next.js project. Choose full for core, auth, i18n, and MCP already wired, or
bare for the core-only kernel. It then drives the dev/build/start lifecycle, manages
the database with Drizzle Kit, generates the RPC route map, and validates environment variables.
No global install — run it through npx or your package manager's dlx.
One command hands over a deployable, authenticated app, so the first version and the production version stay the same application.
SPFN doesn't put your API in a second repo. spfn create --mode full
runs create-next-app with SPFN-recommended flags and then init — which lays
down the server templates, wires the RPC proxy route, adds the Docker and codegen config, and
patches package.json. Full mode adds auth, i18n, and MCP on top of core; use
--mode bare when you deliberately want only the kernel. From there one binary covers every phase:
spfn dev runs the SPFN server and Next.js together, spfn build compiles
both, spfn start serves the built output. The server must report ready before
Next.js launches in dev, and start hard-fails without a prior build.
There is no separate contract layer to maintain. Routes are defined with the
route builder and collected by defineRouter; the client is just
createApi<AppRouter>(), inferring every call from the router's type. The one
generated piece is the route map: the default @spfn/core:route-map generator emits
src/generated/route-map.ts from src/server/router.ts, so the Next.js
RPC proxy at /api/rpc/[routeName] can resolve and forward routes — with cookie
forwarding and interceptors — without ever importing server code. Generators run automatically
during spfn dev and spfn build, and .spfnrc.ts lets you
add your own via the Generator interface.
create-next-app, then a recommended full or core-only bare SPFN foundation.
Adds full or bare SPFN to an existing app — templates, RPC proxy, Docker, scripts.
Installs an ecosystem package and applies its pre-built migrations.
SPFN server + Next.js + codegen watcher; the server signals ready first.
Codegen, Next.js build, tsup-compiled server — then production from the output.
Drizzle Kit wrapped — generate, push, migrate, studio, backup, restore.
Generators from .spfnrc.ts — the route map the RPC proxy depends on.
Schema-driven env files and checks, generated keys, keychain + SOPS secrets.