Next.js UI.
Keep React Server Components, App Router, and Server Actions in Next.js. Move auth, payments, webhooks, rate limiting, and sub-minute crons to a stdlib net/http Go front door.
- external Go dependencies
- external Go dependencies
- stripped static binary
- stripped static binary
- prerendered HTML vs next start
- prerendered HTML vs next start
- SQLite API vs next start
- SQLite API vs next start
End-to-End Workflow
Building blocks for full-stack Go + Next.js
Run `npx @nextgin/adapter init my-app` to generate a clean 3-layer Go backend (httpapi → service → store), httptest suite, typed lib/api.ts client, and repo-local AGENTS.md rules.
Run `nextgin dev` for instant Next.js Turbopack HMR alongside a live Go net/http front door. Auth, cookies, rate limiting, and cron routes run identically to production.
Ship one ~8 MB Go binary + standalone worker to Render 512 MB, Fly.io, or any VPS via `nextgin deploy` with automatic Caddy HTTPS — or split Next.js to Vercel + Go container.
Go supervises Next.js workers over Unix sockets with WriteTimeout: 0 for uninterrupted streaming, while `app.Cron()` + `CronLocker` run reliable every-minute jobs across replicas.
Built on a fast foundation
Everything you need to ship Next.js + Go in production.
Keep React Server Components, App Router, and Server Actions where they shine. Offload the hot path, security boundaries, and background schedules to zero-dependency Go.
Safe defaults before you write line one.
ReadJSON caps bodies at 1 MiB and rejects trailing tokens. ReadRawBody reads exact webhook bytes for constant-time HMAC verification. CORS panics on wildcard origins, and RequireInternal fails closed to 401 when unset.
my-app/ ├── main.go # Thin wiring + app.Cron() ├── internal/ │ ├── domain/ # Types & sentinel errors │ ├── store/ # SQL / sqlc queries │ ├── service/ # Business rules & txns │ └── httpapi/ # DTOs, handlers & httptest ├── lib/api.ts # Typed browser + SSR client ├── app/ # Next.js App Router UI └── AGENTS.md # AI-agent architecture rules
One command scaffolds the full 3-layer layout.
Run npx @nextgin/adapter init my-app for a clean httpapi → service → store Go backend, centralized domain error mapping, fast httptest tests, typed lib/api.ts, and a project AGENTS.md.
Request Routing
One Go front door. Four clean paths.
Handled in Go with 1 MiB body limits, per-IP rate limiting, raw-body HMAC verification, and persistent SQLite/Postgres pooling.
Production Details
Engineered for the edge cases real apps hit.
Beyond raw RPS: process supervision, streaming preservation, webhook integrity, multi-replica cron safety, and single-command deploys.
Unix-Socket Worker Pool
Go supervises N Next.js standalone workers over Unix domain sockets with automatic crash restarts, round-robin dispatch, and graceful drain on SIGTERM.
Streaming-Safe by Default
Self-host mode keeps WriteTimeout disabled so React Suspense boundaries, RSC flight payloads, and Server-Sent Events stream uninterrupted.
Distributed Cron Locking
Plug in a PostgreSQL advisory lock or Redis SET NX lock so rolling deploys and multi-replica clusters never execute the same cron job twice.
Exact-Byte HMAC Webhooks
Read raw request payloads with strict byte caps before signature verification for Stripe, Paystack, or GitHub webhooks — never double-decoded.
Built-In Health & Probes
Internal health endpoints and cron routes are automatically isolated under /_nextgin/ and excluded from exported public Vercel route tables.
One-Command VPS Deploy
Build, ship over SSH, and provision Docker, Caddy automatic HTTPS, PostgreSQL, and Redis on any Ubuntu/Debian VPS without hand-rolled bash scripts.
Single-Owner Data Model
Avoid split-brain ORMs. Let Go own runtime SQL queries and transactions with persistent connection pools while Next.js reads typed JSON via lib/api.ts.
Zero-Downtime Shutdown
In-flight HTTP requests, cron handlers, and Next.js worker pools all respect context cancellation so rolling restarts never drop active checkouts.
AI-Ready Scaffolding
Generates main.go, internal/{domain,store,service,httpapi}, httptest suites, lib/api.ts, and a repo-local AGENTS.md encoding your architectural invariants.
Included in the Repository
Inspect two complete reference apps.
Full seeded SQLite (WAL) storefront: signup/login with HttpOnly sessions, per-IP rate limiting, guest-to-user cart merge, transactional checkout, HMAC payment webhook, and a 1-minute cart-expiry cron.
Clean baseline pairing Next.js App Router SSR, Server Actions, static asset serving from Go, and a live Go API route — verified by automated Node e2e tests on every commit.
Clean Code · Live Proof
Clean separation of concerns — running right now.
This website is served by nextgin itself. Inspect the 3-layer code pattern on the left and ping the live Go server on the right.
func main() {
repo := store.OpenSQLite(dbPath)
svc := service.NewStoreService(repo, webhookSecret)
app, _ := nextgin.New("./.nextgin", nextgin.Config{
Workers: 1,
Port: envOr("PORT", "8080"),
})
// Unlimited in-process cron with SIGTERM cancellation
app.Cron("expire-carts", "* * * * *", func(w http.ResponseWriter, r *http.Request) {
svc.ExpireAbandonedCarts(r.Context(), 15*time.Minute)
w.WriteHeader(http.StatusNoContent)
})
httpapi.NewHandlers(svc).Register(app.Router.Group("/api"))
app.MountFrontend()
log.Fatal(app.Run(":" + port))
}Click “Ping Go” to stream 10 live browser-to-Go RTT measurements.
Measured Performance
Real throughput, same database, zero errors.
Pure-Go nextgin vs plain next start
SQLite API (GET /api/products)
c=20, n=2000Prerendered HTML (GET /)
c=20, n=2000Dynamic SSR (GET /products/1)
c=10, n=300Reproduce this benchmark locally
Measured on the same machine against examples/ecommerce-app reading the exact same WAL-mode SQLite database (modernc.org/sqlite in Go vs Node v26 built-in node:sqlite in app/api/next-products). Dynamic SSR throughput stays close (1.15×) because both run Next.js React rendering; Go shines on prerendered pages and API hot paths.
npm run build -w ecommerce-app (cd examples/ecommerce-app && PORT=8080 ./server) # Compare GET /, GET /api/products vs GET /api/next-products, and GET /products/1
Live telemetry from Go · /api/stats
The nextgin Engine
Zero external Go dependencies.
MIT licensed & built on Go stdlib net/http.
Powering AI-native app devs
Every scaffolded repo includes AGENTS.md so coding agents follow your 3-layer Go + Next.js invariants automatically.
Deployment Topologies
Start on Render or a $5 VPS. Split to Vercel anytime.
Same Go backend and Next.js App Router codebase — pick a single 512 MB container or split web and API across clouds.
Split: Vercel + Go Container
Keep Next.js on Vercel Hobby/Pro while your pure-Go API, webhooks, and crons run on Render, Fly.io, Cloud Run, or Railway with zero Vercel API compute spend.
All-in-One: Render / Fly / Single VPS
One Docker container or one SSH deploy. Go serves static/prerendered pages, APIs, and crons natively while managing Next.js workers over Unix sockets.
FAQ
Common architectural questions.
Honest engineering answers on Vercel split mode, Cloudflare, memory sizing, streaming, cron locking, and database ownership.
Next.js excels at UI, SSR, React Server Components, and Server Actions. Moving auth, sessions, carts, webhooks, rate limiting, and cron jobs to pure Go gives you persistent DB connection pooling, ~15–18× higher API throughput, zero Node event-loop stalls, and a tiny ~8 MB binary with zero external Go dependencies.
Ready in 30 seconds
Scaffold your Next.js + Go app with clean architecture built in.
One command generates the 3-layer Go backend, httptest suite, Next.js adapter, typed API client, and project AGENTS.md.


