Inertia.js Go Adapter

To use Inertia, you must first create an inertia.New instance. You can provide a standard file path for the root template or use embed.FS to embed the template into your binary.

Required parameters:

• url: The application URL used for redirects.
• rootTemplate: The path to your root HTML template.
• version: An optional asset version string.
• embed.FS (optional): An embedded filesystem containing your templates.

url := "http://inertia-app.test" // Application URL for redirect
rootTemplate := "./app.gohtml"   // Root template
version := ""

// Standard initialization
inertiaManager := inertia.New(url, rootTemplate, version)

// Initialization with embedded filesystem
//go:embed template
var templateFS embed.FS
inertiaManager := inertia.New(url, rootTemplate, version, templateFS)

Your root template must provide a way for Inertia to inject the page data.

Standard Template

Use the marshal function to inject the .page object into a JSON script tag.

<body>
    <script data-page="app" type="application/json">{{ marshal .page }}</script>
    <div id="app"></div>
    <script src="js/app.js"></script>
</body>

SSR-Enabled Template

If using Server-Side Rendering, check for the .ssr object to inject the pre-rendered head and body content.

<head>
    {{ if .ssr }}
        {{ raw .ssr.Head }}
    {{ end }}
</head>
<body>
    {{ if not .ssr }}
        <script data-page="app" type="application/json">{{ marshal .page }}</script>
        <div id="app"></div>
    {{ else }}
        {{ raw .ssr.Body }}
    {{ end }}
    <script src="js/app.js"></script>
</body>

Install the inertia-go package using the standard Go toolchain:

go get github.com/petaki/inertia-go

Register the Inertia middleware with your HTTP router (e.g., http.ServeMux) to handle Inertia-specific requests and responses.

mux := http.NewServeMux()
mux.Handle("/", inertiaManager.Middleware(homeHandler))

To enable SSR, you must provide the URL of your Node.js SSR server. Note that Render will return an error if the SSR server fails; it does not automatically fall back to client-side rendering.

Options:

• EnableSsrWithDefault(): Uses the default URL http://127.0.0.1:13714/render.
• EnableSsr(url): Uses a custom URL (e.g., for production or Vite dev server).
• Custom *http.Client: You can provide a client with a custom timeout (the default is 30 seconds).

// Default SSR
inertiaManager.EnableSsrWithDefault()

// Custom SSR URL
inertiaManager.EnableSsr("http://ssr-host:13714/render")

// Vite dev server SSR
inertiaManager.EnableSsr("http://localhost:5173/__inertia_ssr")

// Custom client with timeout
client := &http.Client{
    Timeout: 10 * time.Second,
}
inertiaManager.EnableSsr("http://ssr-host:13714/render", client)

You can modify page settings like flash messages and history behavior using context-based methods. These methods return a new context that must be applied to the request.

// Example: Adding flash messages
ctx := inertiaManager.WithFlash(r.Context(), map[string]any{
    "success": "Item created successfully",
})
r = r.WithContext(ctx)

Use the Render method within your HTTP handlers to serve an Inertia page. You must specify the component name (e.g., home/Index) and a map of props.

func homeHandler(w http.ResponseWriter, r *http.Request) {
    // Render with props
    err := inertiaManager.Render(w, r, "home/Index", map[string]any{
        "total": 32,
    })
    if err != nil {
        // Handle server error...
    }
}

The Location method handles redirects differently depending on whether the request is an Inertia request or a standard browser request:

• Inertia Request: Sets the HeaderLocation and returns a 409 Conflict status. This tells the Inertia frontend to perform a full page reload to the new URL.
• Standard Request: Performs a standard 302 Found redirect.

// Inside a handler
if userNotAuthorized { 
    i.Location(w, r, "/login")
    return
}

You can control Inertia's navigation behavior and flash messages by modifying the request context:

• WithFlash(ctx, data map[string]any): Sets flash messages to be sent in the next response.
• WithClearHistory(ctx): Tells Inertia to clear the browser history.
• WithEncryptHistory(ctx): Tells Inertia to encrypt the history state.
• WithPreserveFragment(ctx): Tells Inertia to preserve the URL fragment (hash).
• WithScrollProp(ctx, key, prop): Sets scroll position properties.

// Example: Redirecting with flash and clearing history
ctx = i.WithFlash(r.Context(), map[string]any{"success": "Profile updated!"})
ctx = i.WithClearHistory(ctx)

// Use the modified context in your handler
err := i.Render(w, r.WithContext(ctx), "Dashboard", nil)

You can share data that will be included in every Inertia response using the following methods:

• Share(key string, value any): Adds a property to the sharedProps map. These are sent to the frontend in every request.
• ShareViewData(key string, value any): Adds data that is available to your Go HTML templates (the root template) but is not necessarily part of the Inertia JSON props.
• ShareFunc(key string, value any): Registers a function in the Go template's FuncMap, making it available within your root template.

i.Share("auth", authUser)

i.ShareViewData("appName", "My Awesome App")

i.ShareFunc("formatDate", myDateFormatterFunc)