Skip to content

Latest commit

 

History

History
357 lines (257 loc) · 10.4 KB

README.md

File metadata and controls

357 lines (257 loc) · 10.4 KB
Raw

Gonertia

gonertia

Gonertia is a well-tested and zero-dependency Inertia.js server-side adapter for Golang. Visit inertiajs.com to learn more.

Latest Release Audit Workflow Go Report Card Go Reference MIT license

Introduction

Inertia allows you to create fully client-side rendered single-page apps without the complexity that comes with modern SPAs. It does this by leveraging existing server-side patterns that you already love.

This package based on the official Laravel adapter for Inertia.js inertiajs/inertia-laravel, supports all the features and works in the most similar way.

Roadmap

  • Tests
  • Helpers for testing
  • Helpers for validation errors
  • Examples
  • SSR
  • Inertia.js v2 compatibility (waiting for stable release, discussion is here: #17)

Inertia.js v2 compatibility

A beta version of Inertia.js 2.0 was recently released.

The new version of Gonertia has already been adapted to all new features.

Click here to try and discuss.

Installation

Install using go get command:

go get github.com/romsar/gonertia

Usage

Basic example

Initialize Gonertia in your main.go:

package main

import (
    "log"
    "net/http"

    inertia "github.com/romsar/gonertia"
)

func main() {
    i, err := inertia.New(rootHTMLString)
    // i, err := inertia.NewFromFile("resources/views/root.html")
    // i, err := inertia.NewFromReader(rootHTMLReader)
    // i, err := inertia.NewFromBytes(rootHTMLBytes)
    if err != nil {
        log.Fatal(err)
    }

    // Now create your HTTP server.
    // Gonertia works well with standard http server library,
    // but you are free to use some external routers like Gorilla Mux or Chi.
    mux := http.NewServeMux()

    mux.Handle("/home", i.Middleware(homeHandler(i)))
}

func homeHandler(i *inertia.Inertia) http.Handler {
    fn := func(w http.ResponseWriter, r *http.Request) {
        err := i.Render(w, r, "Home/Index", inertia.Props{
            "some": "data",
        })

        if err != nil {
            handleServerErr(w, err)
            return
        }
    }

    return http.HandlerFunc(fn)
}

Create root.html template:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<!-- Put here your styles, meta and other stuff -->
		{{ .inertiaHead }}
	</head>

	<body>
		{{ .inertia }}
		<script type="module" src="/build/assets/app.js"></script>
	</body>
</html>

Starter kits

  1. Gonertia + Vue + Vite + Tailwind
  2. Gonertia + Svelte + Vite + Tailwind
  3. Gonertia + React + Vite + Tailwind

More examples

Set asset version (learn more)

i, err := inertia.New(
    /* ... */
    inertia.WithVersion("some-version"), // by any string
    inertia.WithVersionFromFile("./public/build/manifest.json"), // by file checksum
)

SSR (Server Side Rendering) (learn more)

To enable server side rendering you have to provide an option in place where you initialize Gonertia:

i, err := inertia.New(
/* ... */
    inertia.WithSSR(), // default is http://127.0.0.1:13714
    inertia.WithSSR("http://127.0.0.1:1234"), // custom url http://127.0.0.1:1234
)

Also, you have to use asset bundling tools like Vite or Webpack (especially with Laravel Mix). The setup will vary depending on this choice, you can read more about it in official docs or check an example that works on Vite.

Lazy and Always props (learn more)

props := inertia.Props{
    "lazy": inertia.LazyProp{func () (any, error) {
        return "prop", nil
    }},
    "always": inertia.AlwaysProp{"prop"},
}

i.Render(w, r, "Some/Page", props)

Redirects (learn more)

i.Redirect(w, r, "https://example.com") // plain redirect
i.Location(w, r, "https://example.com") // external redirect

NOTES: If response is empty - user will be redirected to the previous url, just like in Laravel official adapter.

To manually redirect back, you can use Back helper:

i.Back(w, r)

Share template data (learn more)

i.ShareTemplateData("title", "Home page")
<h1>{{ .title }}</h1>

Share template func

i.ShareTemplateFunc("trim", strings.TrimSpace)
<h1>{{ trim " foo bar " }}</h1>

Pass template data via context (in middleware)

ctx := inertia.SetTemplateData(r.Context(), inertia.TemplateData{"foo", "bar"})
// or inertia.SetTemplateDatum(r.Context(), "foo", "bar")

// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).

Share prop globally (learn more)

i.ShareProp("foo", "bar")

Pass props via context (in middleware)

ctx := inertia.SetProps(r.Context(), inertia.Props{"foo": "bar"})
// or inertia.SetProp(r.Context(), "foo", "bar")

// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).

Validation errors (learn more)

ctx := inertia.SetValidationErrors(r.Context(), inertia.ValidationErrors{"some_field": "some error"})
// or inertia.AddValidationErrors(r.Context(), inertia.ValidationErrors{"some_field": "some error"})
// or inertia.SetValidationError(r.Context(), "some_field", "some error")

// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).

Replace standard JSON marshaller

  1. Implement JSONMarshaller interface:
import jsoniter "github.com/json-iterator/go"

type jsonIteratorMarshaller struct{}

func (j jsonIteratorMarshaller) Decode(r io.Reader, v interface{}) error {
    return jsoniter.NewDecoder(r).Decode(v)
}

func (j jsonIteratorMarshaller) Marshal(v interface{}) ([]byte, error) {
    return jsoniter.Marshal(v)
}
  1. Provide your implementation in constructor:
i, err := inertia.New(
    /* ... */,
    inertia.WithJSONMarshaller(jsonIteratorMarshaller{}),
)

Use your logger

i, err := inertia.New(
    /* ... */
    inertia.WithLogger(), // default logger
    // inertia.WithLogger(somelogger.New()),
)

Set custom container id

i, err := inertia.New(
    /* ... */
    inertia.WithContainerID("inertia"),
)

Set flash provider

Unfortunately (or fortunately) we do not have the advantages of such a framework as Laravel in terms of session management. In this regard, we have to do some things manually that are done automatically in frameworks.

One of them is displaying validation errors after redirects. You have to write your own implementation of gonertia.FlashProvider which will have to store error data into the user's session and return this data (you can get the session ID from the context depending on your application).

i, err := inertia.New(
    /* ... */
    inertia.WithFlashProvider(flashProvider),
)

Simple inmemory implementation of flash provider:

type InmemFlashProvider struct {
    errors map[string]inertia.ValidationErrors
}

func NewInmemFlashProvider() *InmemFlashProvider {
    return &InmemFlashProvider{errors: make(map[string]inertia.ValidationErrors)}
}

func (p *InmemFlashProvider) FlashErrors(ctx context.Context, errors ValidationErrors) error {
    sessionID := getSessionIDFromContext(ctx)
    p.errors[sessionID] = errors
    return nil
}

func (p *InmemFlashProvider) GetErrors(ctx context.Context) (ValidationErrors, error) {
    sessionID := getSessionIDFromContext(ctx)
    errors := p.errors[sessionID]
    p.errors[sessionID] = nil
    return errors, nil
}

Testing

Of course, this package provides convenient interfaces for testing!

func TestHomepage(t *testing.T) {
    body := ... // get an HTML or JSON using httptest package or real HTTP request.

    // ...

    assertable := inertia.AssertFromReader(t, body) // from io.Reader body
    // OR
    assertable := inertia.AssertFromBytes(t, body) // from []byte body
    // OR
    assertable := inertia.AssertFromString(t, body) // from string body

    // now you can do assertions using assertable.Assert[...] methods:
    assertable.AssertComponent("Foo/Bar")
    assertable.AssertVersion("foo bar")
    assertable.AssertURL("https://example.com")
    assertable.AssertProps(inertia.Props{"foo": "bar"})

    // or work with the data yourself:
    assertable.Component // Foo/Bar
    assertable.Version // foo bar
    assertable.URL // https://example.com
    assertable.Props // inertia.Props{"foo": "bar"}
    assertable.Body // full response body
}

More community adapters

Also, you can check one more golang adapter called petaki/inertia-go.

Full list of community adapters is located on inertiajs.com.

Credits

This package is based on inertiajs/inertia-laravel and uses some ideas of petaki/inertia-go.

License

Gonertia is released under the MIT License.