Inertia

Inertia lets you build a modern React frontend with classic server-side routing. Your Go routers decide which page to show and what data it receives, while React renders it. Since the server drives navigation, there is no client-side router to maintain and no REST layer between your pages and your services. This is the default stack for new Copper projects. The inertia package (from gocopper/pkg) provides the server-side adapter, wired in automatically by copper create.

Rendering a Page

Inject *inertia.Renderer into your router and call Render with a component name and props:

pkg/rockets/router.go

func (ro *Router) HandleRocketsPage(w http.ResponseWriter, r *http.Request) {
	rockets, err := ro.rockets.List(r.Context())
	if err != nil {
		ro.logger.Error("Failed to list rockets", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "rockets",
		Props: map[string]any{
			"rockets": rockets,
		},
	})
}

Components live in web/src/pages/ and receive props directly:

web/src/pages/rockets.tsx

export default function Rockets({ rockets }) {
  return (
    <ul>
      {rockets.map((rocket) => (
        <li key={rocket.id}>{rocket.name}</li>
      ))}
    </ul>
  )
}

On a full page load, Copper renders the HTML shell with the page data embedded. On navigation, Inertia requests only the JSON; the renderer will detect which is which automatically.

Forms

You may read and validate a form submission using ReadForm, which decodes the JSON body and validates its valid: tags (govalidator). On validation failure, the error is flashed automatically and ReadForm returns false, so you simply redirect back:

func (ro *Router) HandleCreateRocket(w http.ResponseWriter, r *http.Request) {
	var form struct {
		Name string `json:"name" valid:"required"`
	}

	if !ro.inertia.ReadForm(w, r, &form) {
		ro.inertia.Redirect303(w, r, "/rockets")
		return
	}

	rocket, err := ro.rockets.Create(r.Context(), form.Name)
	if err != nil {
		ro.inertia.FlashProps(r, map[string]any{
			"error": "Could not create the rocket. Please try again.",
		})
		ro.inertia.Redirect303(w, r, "/rockets")
		return
	}

	ro.inertia.Redirect303(w, r, "/rockets/"+rocket.ID)
}

This is the classic post/redirect/get pattern: mutations always end in Redirect303, and the next render picks up any flashed props. Validation errors appear on the client under flash.validationError.

ReadForm’s two failure modes differ: a body that fails validation flashes the error and leaves the response for you to write, but a body that can’t be decoded as JSON at all writes an error response itself. Both return false.

Flash Props

FlashProps stores props for a single upcoming render, which is perfect for success and error messages across a redirect:

ro.inertia.FlashProps(r, map[string]any{
	"success": "Rocket launched!",
})
ro.inertia.Redirect303(w, r, "/rockets")

The next page render receives them under the flash prop, after which they are gone:

export default function Rockets({ rockets, flash }) {
  return (
    <>
      {flash?.success && <Banner>{flash.success}</Banner>}
      {/* ... */}
    </>
  )
}

Shared Props

ShareProps adds props to the current request’s render from anywhere. It is typically called from a middleware so that every page in a section receives common data:

func (mw *PropsMiddleware) Handle(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		mw.inertia.ShareProps(r.Context(), map[string]any{
			"missionName": mw.config.MissionName,
		})

		next.ServeHTTP(w, r)
	})
}

You may attach the middleware per-route via Middlewares, or globally in pkg/app/handler.go.

ShareProps identifies the request via its request ID, so chttp.SetRequestIDInCtxMiddleware() must be in your global middlewares. Scaffolded projects include it by default. Successive calls for the same request replace previously shared props rather than merging them, so you should share everything in a single call.

Partial Reloads

When the client reloads only specific props (router.reload({ only: ["rockets"] })), you may skip computing everything else with ShouldLoadProp:

props := map[string]any{}

if inertia.ShouldLoadProp(r, "telemetry") {
	props["telemetry"] = ro.rockets.LoadTelemetry(ctx)
}

ShouldLoadProp returns true on full renders and only for the requested props on partial reloads.

Deferred Props

Deferred props let a page render immediately while slow data loads in a follow-up request. Declare them in DeferredProps, and guard the expensive work with ShouldLoadDeferredProp:

func (ro *Router) HandleMissionControl(w http.ResponseWriter, r *http.Request) {
	props := map[string]any{
		"mission": ro.rockets.Mission(r.Context()),
	}

	if inertia.ShouldLoadDeferredProp(r, "telemetry") {
		props["telemetry"] = ro.rockets.LoadTelemetry(r.Context())
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "mission-control",
		Props:     props,
		DeferredProps: map[string][]string{
			"default": {"telemetry"},
		},
	})
}

Unlike ShouldLoadProp, ShouldLoadDeferredProp returns false on the initial render: the prop is stripped from the first response and fetched immediately afterwards. On the client, wrap the slow section in Inertia’s <Deferred>:

<Deferred data="telemetry" fallback={<Spinner />}>
  <TelemetryPanel />
</Deferred>

Customizing the Renderer

The renderer is immutable; each With* method returns a copy, so you may configure it once in your constructor:

func NewRouter(p NewRouterParams) *Router {
	return &Router{
		inertia: p.Inertia.WithBasePath("/admin"),
	}
}

WithBasePath(path) mounts a section under a URL prefix. Redirects and page URLs have the prefix stripped so that client-side paths stay clean; it pairs with chttp.base_path.
WithLayoutTemplate(name) renders pages inside a different layout than main.html.
WithComponent(name) sets a default component for all renders.

RenderParams accepts per-render LayoutTemplate and BasePath overrides too.

Server-Side Rendering

SSR is opt-in. Run the Inertia SSR server (see the Inertia SSR guide) and enable it in config:

[inertia]
ssr = true
ssr_server = "http://localhost:13714"

Copper sends each page to the SSR server and injects the rendered HTML. If the SSR server is down or errors, Copper logs a warning and falls back to client-side rendering, so SSR will never take your pages down.

Configuration

Key	Default	Description
`ssr`	`false`	Render pages through an Inertia SSR server
`ssr_server`	`http://localhost:13714`	Address of the SSR server

Getting Started

The Basics

Architecture

HTTP

Database

Frontend

Digging Deeper

Reference

Rendering a Page

Forms

Flash Props

Shared Props

Partial Reloads

Deferred Props

Customizing the Renderer

Server-Side Rendering

Configuration

​Rendering a Page

​Forms

​Flash Props

​Shared Props

​Partial Reloads

​Deferred Props

​Customizing the Renderer

​Server-Side Rendering

​Configuration

Rendering a Page

Forms

Flash Props

Shared Props

Partial Reloads

Deferred Props

Customizing the Renderer

Server-Side Rendering

Configuration