Guide

A Go backend with a React frontend

This is the most common shape for new Go web work, and almost every tutorial about it stops at "Gin serves JSON, React fetches it". That part takes an afternoon. The four problems that take the rest of the quarter are never in the tutorial.

They are: keeping the two sides' idea of your data in step, authentication across two origins, the development proxy, and whether you deploy one artefact or two. Each has two or three real answers and one popular wrong one.

Star counts and activity dates checked against each project's source on 13 November 2026. Numbers move; the reasoning does not.

Problem 1: the types drift

You have a Go struct and a TypeScript interface describing the same record. Nothing connects them. Somebody renames a field in Go, the compiler is happy, the frontend builds, and a form silently posts a field the API ignores. This is the single largest source of bugs in this architecture and the easiest to prevent.

Hand-written types

What most projects do. It works until the second developer, then drifts permanently. If you do this, at least keep the interfaces in one file so the drift is visible in review.

OpenAPI as the source of truth

Annotate the handlers, generate a specification, generate a TypeScript client from it. Tools: swaggo for the spec and openapi-ts for the client. Robust, and the annotations are a second description of the handler that can itself drift.

Design first with goa or protobuf

Write the contract, generate both sides. The strongest guarantee here, and the biggest change to how the team works: the design file becomes the thing you edit first, every time.

Generate TypeScript from the Go types

The Go struct stays the source of truth and a command writes the TypeScript. No second description to maintain. This is what Grit does, extended to the validation schema and the data-fetching hooks as well.

Keeping Go and TypeScript types in step
ApproachSource of truthExtra artefactCatches a rename
Hand-writtenNothing
OpenAPI from annotationsAnnotations
Design first (goa, protobuf)A design file
Generate from Go typesThe Go struct

Problem 2: authentication across two origins

In development the frontend is on localhost:3000 and the API on localhost:8080. That is cross-origin, and it decides your auth design more than any security argument will.

Tokens in localStorage

The most common choice and the weakest. Any script on the page can read the token, so one compromised dependency is one stolen session. It is popular because it is the only option that needs no thought about cookies.

HttpOnly cookies

JavaScript cannot read them, which removes that whole class of theft. The cost is that you now care about SameSite, about CSRF protection on state-changing requests, and about serving both sides from one origin in production or configuring CORS with credentials carefully.

The pattern worth copying

A short-lived access token in memory, a refresh token in an HttpOnly, SameSite cookie scoped to the refresh path, rotation on every use, and replay detection so a stolen refresh token kills the session rather than extending it. More to build, and it is the design that holds up.

Problem 3: the development proxy

The two-origin problem goes away if, in development, the frontend dev server proxies /api to Go. Then the browser sees one origin, cookies work normally and CORS stops being a daily irritation.

vite.config.ts
export default defineConfig({
server: {
proxy: {
// The browser sees one origin, so cookies and CSRF behave
// in development exactly as they will in production.
'/api': { target: 'http://localhost:8080', changeOrigin: true },
},
},
})

Next.js does the same through rewrites. Either way, the rule is: make development match production's origin model, rather than making production match development's convenience.

Problem 4: one artefact or two

Two services

A Go container and a Node or static container behind one domain. Each scales and deploys on its own, the frontend can use server-side rendering, and you are running and paying for two things.

One binary

Build the React app to static files and embed them in the Go binary with go:embed. One artefact, no Node in production, one port, trivial rollback. You give up server-side rendering, so it suits applications behind a login more than marketing pages.

main.go
//go:embed all:web
var frontend embed.FS
// One binary serves the API and the React app. The SPA's routes are
// handled by returning index.html for anything the API did not match.

For an internal tool or a dashboard this is usually the better trade, and it is surprisingly rare because the tutorials do not mention it.

One repository or two

One repository, nearly always. The frontend and the API change together more often than either changes alone, and a single pull request that moves both is the entire benefit. Two repositories make sense when the clients genuinely have separate release cycles, which is rarer than teams assume at the start.

With one repository you can put shared types in a workspace package that both sides import, which is where the type problem above stops being a problem.

Where Grit fits

Grit is an answer to all four at once, for teams who would rather not solve them again.

  • Types: the Go model generates the TypeScript type, the Zod validation schema and the React Query hooks. grit sync re-runs it, so a renamed field is a compile error rather than a silent bug.
  • Auth: short-lived access tokens with refresh tokens in HttpOnly cookies, rotation and replay detection, sessions you can revoke per device.
  • Proxy: the dev server is configured to proxy the API, so development and production share an origin model.
  • Deployment: both shapes. A monorepo of two services, or a single binary with the SPA embedded.

Frequently asked questions

Can Go serve a React app?

Yes. Build the React app to static files and embed them with go:embed, then serve index.html for any path the API did not match. One binary, no Node in production. You lose server-side rendering, which matters for public pages and rarely for an application behind a login.

How do I share types between Go and TypeScript?

Three real options: generate an OpenAPI specification from handler annotations and a client from that; design first with goa or protobuf and generate both sides; or generate the TypeScript directly from the Go structs. Hand-writing both is the fourth and it drifts.

Should I use JWT or sessions with a React frontend?

Either works; where you put the credential matters more. A token in localStorage is readable by any script on the page. Prefer a short-lived token held in memory with a refresh token in an HttpOnly, SameSite cookie, rotated on use.

Do I need CORS?

Only if the browser sees two origins. Proxy /api through the frontend dev server in development, and serve both from one origin in production, and the question mostly disappears. If you do need it, allow specific origins rather than *, which cannot carry credentials anyway.

Next.js or Vite with a Go backend?

Vite if the application is behind a login: it builds to static files you can embed in the Go binary. Next.js if you need server-side rendering for public pages, which means running Node in production alongside Go.

Keep reading