Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Generate TypeScript types for the frontend

Generate TypeScript types for the frontend

Since v0.6.0

Give the frontend the types of the app’s Go code: the inputs and results of the API’s handlers, with a client that calls them, and the props of the Inertia pages. The types are generated from the Go types, so when a field changes in Go, TypeScript’s type checks find what to change in the frontend.

Before you start

Steps

1. Register the types command

In main.go’s setup, after the routes:

// illustrative
if err := typescript.Register(app, srv, typescript.Config{
	Prefix:  "/api/v1", // the API's routes: api.ts's client calls them
	Inertia: in,        // the Inertia pages' props: pages.ts
}); err != nil {
	return nil, err
}

Config.Dir is where the files go, frontend/src/types by default. A frontend in another repository can take them from there, or you can point Dir into it.

2. List the Inertia pages

With Inertia, list the pages in inertia.New, so the generator knows them:

func setup(app *anetos.App) (*web.Server, error) {
	srv, err := web.NewServer(app)
	if err != nil {
		return nil, err
	}
	sessions, err := session.New(app)
	if err != nil {
		return nil, err
	}
	if _, err := vite.New(app, public.Files, vite.WithReactRefresh()); err != nil {
		return nil, err
	}
	shared := func(*web.Ctx) (Shared, error) { return Shared{AppName: app.Config().Name}, nil }
	in, err := inertia.New(app, root(), inertia.WithShared(shared), inertia.WithPages(notesIndex, notesCreate))
	if err != nil {
		return nil, err
	}

	r := srv.Router()
	r.ErrorPages(inertia.ErrorPages("Error"))
	r.Get("/build/{path...}", web.WrapHandler(vite.Handler()))
	h := notes{store: newStore()}
	g := r.Group("", sessions.Middleware, web.CSRF(web.WithXSRFCookie()), inertia.Middleware)
	g.Get("/", func(c *web.Ctx) error { return c.RedirectRoute("notes.index") })
	g.Get("/notes", h.index).Name("notes.index")
	g.Get("/notes/new", h.create).Name("notes.create")
	g.Post("/notes", web.H(h.save))
	g.Delete("/notes/{id}", h.delete)
	g.Get("/boom", func(*web.Ctx) error { return web.Error(http.StatusTeapot, "This page is a teapot.") })

	// go run . types writes the pages' props as TypeScript, in
	// frontend/src/types (anetos dev does after each build).
	if err := typescript.Register(app, srv, types(in)); err != nil {
		return nil, err
	}
	return srv, nil
}

// types is where the frontend's TypeScript types come from.
func types(in *inertia.Inertia) typescript.Config {
	return typescript.Config{Inertia: in}
}

(Copied from examples/inertia, region setup.)

In development and tests, once the app lists pages, rendering a page that isn’t listed fails, saying to add it. A package of handlers can export its pages for setup to list (var Pages = []inertia.AnyPage{…}).

3. Write the files

go run . types

writes frontend/src/types/api.ts and, with Inertia, frontend/src/types/pages.ts; with Routes: true in the Config, frontend/src/types/routes.ts too, the named routes for links (route('posts.show', { id }); since v0.6). Commit them. go tool anetos generate runs the command, go tool anetos dev runs it after each build, and go tool anetos check and build run it before the frontend’s build, so the files follow the Go code as you edit, and the type check sees them as they are; a file whose content didn’t change isn’t written again. (In development the browser runs what Vite serves without a type check: the check is the build’s, npm run build, which check and build run.)

4. Use the types

A page component takes its props’ type from pages.ts:

// illustrative: frontend/src/pages/Notes/Index.tsx
import type { PageProps } from '../../types/pages'

export default function Index({ notes = [], next, stats }: PageProps<'Notes/Index'>) {
  // notes: Note[], next: number, stats?: Stats
}

PageProps<'Notes/Index'> is the page’s props, the shared props and errors. pages.ts also tells Inertia’s client the shared props' type, so usePage().props.appName is typed in any component. A Prop field is optional in TypeScript (stats?), since a deferred or optional prop is left out of the first visit.

A form takes its input’s type from api.ts (the typed handler’s input, NoteInput):

// illustrative
import type { NoteInput } from '../../types/api'

const form = useForm<NoteInput>({ title: '', body: '' })

5. Call the API

api.ts has a function for each typed handler at or below Config.Prefix, named after the route’s name (posts.show is api.posts.show); an unnamed route’s is its handler’s method or function (Posts.Index is api.posts.index), else its method and path (getApiV1Posts), so name the routes the frontend calls. An API project’s routes are named api.… (api.posts.show), so its functions are under api: createApi().api.posts.show(…).

// illustrative
import { createApi, ApiError } from './types/api'

const api = createApi()
const post = await api.posts.show({ id: 1 }) // Post
try {
  await api.posts.create({ title: '' })
} catch (e) {
  if (e instanceof ApiError) console.log(e.status, e.problem.errors) // 422, { title: '…' }
}

A function takes one object: the path, query and header parameters by their names (id, page), and the body’s fields by their JSON names. It sends JSON, or a multipart form when the input has files, and resolves to the result’s type (nothing for 204). An error status rejects with an ApiError holding the problem details. createApi’s options:

OptionDoes
baseUrlThe API’s origin when it isn’t the page’s (https://api.example.com)
tokenAn API token, or a function returning it: sent as Authorization: Bearer
credentialssame-origin by default; include sends cookies to another origin too (the XSRF header goes when the page can read the XSRF-TOKEN cookie: a cookie domain both share)
headersHeaders for every request
fetchThe fetch to use

On the page’s origin, the session’s cookie and the XSRF-TOKEN cookie go with each call (X-XSRF-TOKEN for a post), as web.CSRF expects with web.WithXSRFCookie().

Complete example

examples/inertia types its pages from frontend/src/types/pages.ts, which its setup registers and a test keeps up to date.

How it works

The types are built from the Go types at run time, with the JSON Schemas of the OpenAPI document: a struct as encoding/json writes it (its json names, omitempty, embedded structs), a named struct as an interface of its name, and an input’s validate rules where TypeScript can say them (required makes a field required, in makes a union of the values). time.Time is a string, []byte a base64 string, a pointer T | null.

Note: a nil slice or map is written as null by encoding/json, while its type says it’s an array or an object: return empty ones ([]Post{}) from handlers whose clients rely on it.

The command runs the app’s setup, for its routes and pages, without starting it: it needs the app’s settings (APP_KEY), not its database. So does go tool anetos generate --check in CI, which runs it.

pages.ts imports types from @inertiajs/core, which the Inertia adapter (@inertiajs/react, -vue3 or -svelte) installs; with pnpm, whose packages see only their own dependencies, add @inertiajs/core to the frontend’s.

Testing it

A test fails when the files are out of date:

// The frontend's TypeScript types are those of the Go types: a change to
// a page's props without go run . types fails here.
func TestTypes(t *testing.T) {
	app := anetostest.New(t, setup)
	in := anetos.MustResolve[*inertia.Inertia](app.App)
	if err := typescript.Check(app.Router(), types(in)); err != nil {
		t.Error(err)
	}
}

(Copied from examples/inertia/main_test.go, region types-test.)

In an API project, with the Config that main.go registers:

// illustrative
func TestTypes(t *testing.T) {
	app := anetostest.New(t, setup)
	if err := typescript.Check(app.Router(), typescript.Config{Prefix: routes.OpenAPI.Prefix}); err != nil {
		t.Fatal(err)
	}
}

go run . types --check does the same, without a test.

Common problems

SymptomCauseFix
inertia: the page "…" isn't in inertia.WithPagesA page rendered in development or a test isn’t listedAdd it to inertia.WithPages
typescript: frontend/src/types/api.ts is out of dateA Go type changed without the filesRun go run . types (or go tool anetos generate), and commit the files
A route has no function in the clientIt isn’t a typed handler (web.H), or it’s outside Config.PrefixRoute it with web.H, under the prefix
A result is unknownThe handler’s result is a web.Responder or an interfaceReturn the type itself
A type is Record2, or HandlersOrderIts Go name is one TypeScript or the files have (Record, Pages), or two packages have a type of that nameUse the name given, or rename the Go type
warning: … the header X-Tags is a listThe client sends a list header as one value, its items joined by commasRead the list from the query instead

Next steps