Build a single-page app
Since v0.6.0
Give an API project a single-page app (SPA): a frontend in React,
Svelte, Vue, or plain TypeScript or JavaScript, which Vite builds, the app’s binary embeds
and serves at /, and which calls the API with a client generated from
the handlers’ Go types. In development, Vite serves it with hot reload
and forwards /api to the app; the SPA logs in with a session cookie.
One binary then holds the API and the SPA: one origin, so no CORS and no shared cookie domain, and one thing to deploy. For an SPA that lives elsewhere (another repository, a CDN, a framework with its own server), see The SPA elsewhere.
Before you start
- An API project (
anetos new shop --stack=api; Tutorial: build an API), with accounts if the SPA logs in (go tool anetos make:auth; Add accounts to an API). - Node.js 20.19 or later in 20, or 22.12 or
later, with npm (the packages you add may ask for more: React Router
8, which
examples/spauses, needs 22.22 or later). Only the frontend needs it: the Go app doesn’t, and neither do its tests.
Steps
1. Add the SPA
In an API project, after make:auth if it has accounts:
go tool anetos vite:install # TypeScript; --js for JavaScriptThe SPA’s page is written for the routes there are when you run it:
after make:auth, the page logs in; before it, the page shows the
API’s welcome, and running make:auth later doesn’t change it (write
the login yourself then, as examples/spa does). A new
project without accounts can have it from the start:
anetos new shop --stack=api --vite # --vite=js for JavaScriptEither writes a working SPA without a framework, and wires it:
| File | What it holds |
|---|---|
frontend/package.json, tsconfig.json, go.mod | Vite and TypeScript; the go.mod keeps the go command out of node_modules |
frontend/vite.config.ts | Vite’s address (localhost:5173), the forwarding of /api to the app, the build into ../public/spa |
frontend/index.html, src/main.ts, src/style.css | The page: with make:auth’s routes, a login (with two-factor codes), a registration form, a logout, and the /verify-email and /reset-password pages the account emails link to; without them, the API’s welcome |
frontend/src/types/api.ts | The API’s client, written by go run . types (see Generate TypeScript types) |
public/public.go | public.Files: the folder, with the build in spa/, embedded in the binary |
main.go | typescript.Register (the client) and vite.SPA as the router’s fallback (step 4) |
.env, .env.example | Vite’s address and APP_URL in HTTP_SPA_ORIGINS, so the SPA logs in with the session |
deploy/production.env.example | APP_URL in HTTP_SPA_ORIGINS (and AUTH_CLIENT_URL: the account emails link to the SPA) |
.gitignore, .dockerignore, Dockerfile | The build and node_modules left out; a Node stage that builds the SPA |
Then it installs the packages with npm (--skip-install skips it).
2. Run it
go tool anetos devOpen http://localhost:5173, Vite’s address: Vite serves the SPA from
frontend/, updating it as you edit, and forwards /api to anetos dev’s address (127.0.0.1:8080, HTTP_ADDR), which serves the app
and rebuilds it as the Go code changes, writing the client again when a
route or a handler’s types change. The address and the forwarding are in vite.config.ts:
server: {
port: 5173,
strictPort: true, // HTTP_SPA_ORIGINS and AUTH_CLIENT_URL in .env name it
proxy: { '/api': 'http://127.0.0.1:8080' },
},(Copied from examples/spa/frontend/vite.config.ts, region server.)
The page and the API are one origin for the browser (Vite’s), as they
are in production (the app’s). With another HTTP_ADDR, or another
port for Vite, change them here, with HTTP_SPA_ORIGINS and
AUTH_CLIENT_URL in .env: the tool writes the defaults.
3. Write the SPA
The SPA is yours: add a framework and a router with npm, in
frontend/. For React, with React Router:
cd frontend
npm install react react-dom react-router
npm install -D @vitejs/plugin-react @types/react @types/react-domthen add react() to plugins in vite.config.ts, "jsx": "react-jsx" to tsconfig.json, and point index.html at
src/main.tsx. Svelte (@sveltejs/vite-plugin-svelte) and Vue
(@vitejs/plugin-vue) take their plugin the same way; their components
need their own type checker in the build script (svelte-check,
vue-tsc --noEmit) in place of tsc --noEmit, and both run on
TypeScript 6, not the 7 vite:install writes: npm install -D typescript@^6 svelte-check (or vue-tsc), and add the .svelte (or
.vue) files to tsconfig.json’s include. examples/spa
is a React SPA made like this: its pages are routes of the browser’s
path, which the app answers with index.html (step 4):
createRoot(document.getElementById('root')!).render(
<StrictMode>
<BrowserRouter>
<AuthProvider>
<Routes>
<Route element={<Layout />}>
{/* Two keys: the lists don't share their state. */}
<Route index element={<RequireUser><Bookmarks key="current" /></RequireUser>} />
<Route path="archived" element={<RequireUser><Bookmarks key="archived" archived /></RequireUser>} />
<Route path="login" element={<GuestOnly><Login /></GuestOnly>} />
<Route path="register" element={<GuestOnly><Register /></GuestOnly>} />
<Route path="forgot-password" element={<GuestOnly><ForgotPassword /></GuestOnly>} />
{/* The account emails link to these two (AUTH_CLIENT_URL). */}
<Route path="reset-password" element={<ResetPassword />} />
<Route path="verify-email" element={<VerifyEmail />} />
<Route path="*" element={<NotFound />} />
</Route>
</Routes>
</AuthProvider>
</BrowserRouter>
</StrictMode>,
)(Copied from examples/spa/frontend/src/main.tsx, region routes.)
Call the API with the generated client, whose functions are named after
the routes (the route named api.login is client.api.login, which
api.ts below exports as api.login), with the handlers’ input and
result types. A 422’s problem details carry a message per field:
import { ApiError, createApi } from './types/api'
export const api = createApi().api
// errorMessages says what went wrong: a 422's message per field of the
// input ({ email: "…" }), otherwise the error's message, under "".
export function errorMessages(err: unknown): Record<string, string> {
if (err instanceof ApiError) {
return err.problem.errors ?? { '': err.message }
}
return { '': err instanceof Error ? err.message : String(err) }
}(Copied from examples/spa/frontend/src/api.ts, region client.)
The client sends the session cookie and the XSRF-TOKEN cookie back in
the X-XSRF-TOKEN header: the login is the session’s, as Log in from
your SPA describes. When the SPA starts, api.me() says
who is logged in (or 401; the browser’s console notes a 401 or 422
answer as a failed request, which is the browser’s, not an error of
the page).
make:crud’s endpoints go in routes/api.go’s group, open to every
client and without sessions: for the SPA’s logged-in user to reach
them, call them from routes/auth.go with its loggedIn group, as the
generated comment says, and make each record its user’s as Build an
API does. The account emails link to the SPA’s
/verify-email and /reset-password pages (AUTH_CLIENT_URL), which
send the link’s token to the API.
4. Serve it from the app
vite:install wrote this in main.go’s setup, after the routes:
// `go run . types`: the client of the API in frontend/src/types, which
// the SPA calls it with (anetos dev updates it).
if err := typescript.Register(app, srv, typescript.Config{Prefix: routes.OpenAPI.Prefix}); err != nil {
return nil, err
}
// The single-page app (frontend/), which Vite builds into public/spa:
// at /, for the paths the routes don't take, but /api/'s. In
// development, open Vite's address instead (anetos dev runs it).
spa, err := vite.SPA(app, public.Files, vite.Except("/api/"))
if err != nil {
return nil, err
}
srv.Router().Fallback(spa)(Copied from examples/spa/main.go, region spa-serve.)
The routes come first; for a request none of them takes, the SPA’s handler answers:
| Request | Answer |
|---|---|
A GET or HEAD for a file of the build (GET /assets/index-Bx1.js) | The file: those under assets/, named by a hash of their content, cached for a year; the others revalidated |
A GET or HEAD for /, or for a page’s path from a browser (GET /bookmarks/12, Accept: text/html) | index.html, whose router shows the page |
A path under /api/ (vite.Except), from a browser too | 404, as problem details |
Anything else (POST /login, a missing file, Accept: application/json, /index.html by its name from a program) | 404, as problem details |
5. Build for production
go tool anetos buildbuilds the SPA (npm run build: TypeScript’s checks, in TypeScript,
then vite build into public/spa), then the binary, which embeds it. The Dockerfile
builds the SPA in a Node stage, then the binary with --no-frontend.
Where the app is deployed (APP_ENV production or staging), a binary
built without the SPA refuses to start, saying so.
In production’s settings, the SPA’s origin is APP_URL’s:
APP_URL=https://shop.example.com
HTTP_SPA_ORIGINS=https://shop.example.com
AUTH_CLIENT_URL=https://shop.example.com # with make:authvite:install wrote them in deploy/production.env.example. The app’s
doctor command, run with the production settings (./shop doctor),
warns when HTTP_SPA_ORIGINS doesn’t list APP_URL’s origin. See Deploy.
The SPA elsewhere
The API serves other frontends too; vite.SPA is for the one it ships.
- Another repository, or a CDN. Build the SPA there, and list its
origin in
HTTP_SPA_ORIGINS. On another subdomain than the API (app.example.comcallingapi.example.com), setSESSION_DOMAINand call the API withcreateApi({ baseUrl: 'https://api.example.com', credentials: 'include' }); on another site, the SPA logs in with a token (Log in from your SPA). Write the client into the other repository withtypescript.Config{Dir: …}, or copyapi.tsthere in your build. - A framework with its own server (Next.js, Nuxt, SvelteKit). Run
it as an app of its own, beside the API. Its pages in the browser
call the API as an SPA elsewhere does; its server’s code calls it
with an API token, and can use the generated client too
(
createApi({ baseUrl: 'https://api.example.com', token: process.env.API_TOKEN })).
Complete example
examples/spa is the API of
examples/bookmarks with a React SPA:
login with two-factor codes, registration, password reset, email
verification, and the bookmarks, through the generated client. Its
tests run without Node.
How it works
vite.SPA(app, files, opts...)serves the build infiles'spa/folder (public.Files): Vite writes it there (outDir: '../public/spa', base/), naming its files without the leading_or.that//go:embedleaves out. A file’s ETag is a hash of its content; text of 1 KiB or more goes gzipped to clients that take it. Only the files underspa/are served (notpublic.go), never dot files, andindex.htmlonly as the page. The page and the 404 depend on theAcceptheader, so they carryVary: Accept.r.Fallback(h)is the router’s handler for the requests no route takes, afterr.Static’s files and before the 404. A path with routes for other methods still answers 405 (Routing).- Without the build (tests,
go run .beforenpm run build), the SPA’s paths answer 404 with a page that says to build it, outside production and staging, where the app refuses to start instead. - Development. In an API project whose
main.gocallsvite.SPA,anetos devruns Vite with itsvite.config’s address (node frontend/node_modules/vite/bin/vite.js --clearScreen false), andanetos buildandanetos checkbuild the frontend; an API project’sfrontend/without it is an app of its own, which they leave alone.
Testing it
The Go tests run without Node, with or without the build: test the API
as before,
check that the client is up to date (typescript.Check; see
Generate TypeScript types), and that the
SPA’s paths and the API’s are apart:
func TestSPAPages(t *testing.T) {
app := anetostest.New(t, setup)
app.WithHeader("Accept", "text/html,application/xhtml+xml,*/*;q=0.8")
for _, path := range []string{"/", "/archived", "/verify-email?token=x"} {
app.Get(path).AssertHeader("Content-Type", "text/html; charset=utf-8")
}
app.Get("/api/v1/no-such-thing").AssertNotFound().
AssertHeader("Content-Type", "application/problem+json")
app.Get("/api/v1/bookmarks").AssertStatus(http.StatusUnauthorized).
AssertHeader("Content-Type", "application/problem+json")
}(Copied from examples/spa/spa_test.go, region spa-test.)
Test the SPA itself with the tools of its framework (Vitest, Playwright),
against anetos dev or the built binary.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| http://localhost:8080 shows “The frontend isn’t built” | In development, the SPA is Vite’s | Open http://localhost:5173; or build it (npm run build in frontend/) for the app to serve it |
| Vite: “Port 5173 is already in use” | Another Vite runs there (strictPort) | Stop it, or change the port in vite.config.ts, HTTP_SPA_ORIGINS and AUTH_CLIENT_URL together |
Vite: “http proxy error” for /api/… | The app isn’t on 127.0.0.1:8080 (another HTTP_ADDR or --addr), or it is restarting | Change the proxy’s target in vite.config.ts; wait for anetos dev’s “ready” |
| The login answers a token, and the next request is 401 | The page’s origin isn’t in HTTP_SPA_ORIGINS | List the address the browser shows: http://localhost:5173 in development, APP_URL’s in production |
| An API path answers the SPA’s page | vite.SPA without vite.Except("/api/") | Add it |
| The app refuses to start: “public/spa/index.html is missing” | A production binary built without the frontend | Build with anetos build (or the Dockerfile), not go build alone |
go vet ./... reports packages in frontend/node_modules | No frontend/go.mod | Keep the go.mod vite:install wrote |
Next steps
- Log in from your SPA with a session cookie: how the login works, and an SPA on another subdomain.
- Generate TypeScript types for the frontend: the client and its options.
- Bundle JavaScript and CSS with Vite: a web project’s frontend, for its pages.
- Deploy.
- Protect your app in the browser: CORS and a Content-Security-Policy for the SPA.
- Move htmx pages to an API and an SPA, for a web project.