gonertia

package module
v1.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2024 License: MIT Imports: 16 Imported by: 6

README

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 2.0 compatibility

Installation

Install using go get command:

go get github.com/romsar/gonertia@2.x

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
  4. Also you can use Alpacaproj project generator
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.

Optional and Always props (learn more)
props := inertia.Props{
    "optional": inertia.Optional{func () (any, error) {
        return "prop", nil
    }},
    "always": inertia.Always("prop"),
}

i.Render(w, r, "Some/Page", props)
Merging props (learn more)
props := inertia.Props{
    "merging": inertia.Merge([]int{rand.Int63()}),
}
Deferred props (learn more)
props := inertia.Props{
    "defer_with_default_group": inertia.Defer(func () (any, error) {
        return "prop", nil
    }),
    "defer_with_custom_group": inertia.Defer("prop", "foobar"),
    "defer_with_merging": inertia.Defer([]int64{rand.Int63()}).Merge(),
}
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 any) error {
    return jsoniter.NewDecoder(r).Decode(v)
}

func (j jsonIteratorMarshaller) Marshal(v any) ([]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
    clearHistory map[string]bool
}

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]
    delete(p.errors, sessionID)
    return errors, nil
}

func (p *InmemFlashProvider) FlashClearHistory(ctx context.Context) error {
    sessionID := getSessionIDFromContext(ctx)
    p.clearHistory[sessionID] = true
    return nil
}

func (p *InmemFlashProvider) ShouldClearHistory(ctx context.Context) (bool, error) {
    sessionID := getSessionIDFromContext(ctx)
    clearHistory := p.clearHistory[sessionID]
    delete(p.clearHistory, sessionID)
    return clearHistory
}
History encryption (learn more)

Encrypt history:

// Global encryption:
i, err := inertia.New(
    /* ... */
    inertia.WithEncryptHistory(),
)

// Pre-request encryption:
ctx := inertia.SetEncryptHistory(r.Context())

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

Clear history:

ctx := inertia.ClearHistory(r.Context())

// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).
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"})
    assertable.AssertEncryptHistory(true)
    assertable.AssertClearHistory(true)
    assertable.AssertDeferredProps(map[string][]string{"default": []string{"foo bar"}})
    assertable.AssertMergeProps([]string{"foo"})

    // 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.EncryptHistory // true
    assertable.ClearHistory // false
    assertable.MergeProps // []string{"foo"}
    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.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddValidationErrors added in v1.3.0 

func AddValidationErrors(ctx context.Context, errors ValidationErrors) context.Context

AddValidationErrors appends validation errors to the passed context.

func ClearHistory added in v1.3.5 

func ClearHistory(ctx context.Context) context.Context

ClearHistory cleaning history state.

func ClearHistoryFromContext added in v1.3.5 

func ClearHistoryFromContext(ctx context.Context) bool

ClearHistoryFromContext returns clear history value from the context.

func EncryptHistoryFromContext added in v1.3.5 

func EncryptHistoryFromContext(ctx context.Context) (bool, bool)

EncryptHistoryFromContext returns history encryption value from the context.

func IsInertiaRequest 

func IsInertiaRequest(r *http.Request) bool

IsInertiaRequest returns true if the request is an Inertia request.

func SetEncryptHistory added in v1.3.5 

func SetEncryptHistory(ctx context.Context, encrypt ...bool) context.Context

SetEncryptHistory enables or disables history encryption.

func SetProp added in v1.3.0 

func SetProp(ctx context.Context, key string, val any) context.Context

SetProp sets prop value to the passed context.

func SetProps added in v1.3.0 

func SetProps(ctx context.Context, props Props) context.Context

SetProps sets props values to the passed context.

func SetTemplateData added in v1.3.0 

func SetTemplateData(ctx context.Context, templateData TemplateData) context.Context

SetTemplateData sets template data to the passed context.

func SetTemplateDatum added in v1.3.0 

func SetTemplateDatum(ctx context.Context, key string, val any) context.Context

SetTemplateDatum sets single template data item to the passed context.

func SetValidationError added in v1.3.0 

func SetValidationError(ctx context.Context, key string, msg string) context.Context

SetValidationError sets validation error to the passed context.

func SetValidationErrors added in v1.3.0 

func SetValidationErrors(ctx context.Context, errors ValidationErrors) context.Context

SetValidationErrors sets validation errors to the passed context.

Types

type AlwaysProp added in v1.0.7 

type AlwaysProp struct {
	Value any
}

AlwaysProp is a property that will always evaluated.

https://inertiajs.com/partial-reloads

func Always added in v1.3.5 

func Always(value any) AlwaysProp

func (AlwaysProp) Prop added in v1.1.5 

func (p AlwaysProp) Prop() any

type AssertableInertia added in v1.0.2 

type AssertableInertia struct {
	Body *bytes.Buffer
	// contains filtered or unexported fields
}

AssertableInertia is an Inertia response struct with assert methods.

func AssertFromBytes added in v1.0.4 

func AssertFromBytes(t t, body []byte) AssertableInertia

AssertFromBytes creates AssertableInertia from the bytes body.

func AssertFromReader added in v1.3.0 

func AssertFromReader(t t, body io.Reader) AssertableInertia

AssertFromReader creates AssertableInertia from the io.Reader body.

func AssertFromString added in v1.0.4 

func AssertFromString(t t, body string) AssertableInertia

AssertFromString creates AssertableInertia from the string body.

func (AssertableInertia) AssertClearHistory added in v1.3.5 

func (i AssertableInertia) AssertClearHistory(want bool)

AssertClearHistory verifies that clear history value from Inertia response and the passed value are the same.

func (AssertableInertia) AssertComponent added in v1.0.2 

func (i AssertableInertia) AssertComponent(want string)

AssertComponent verifies that component from Inertia response and the passed component are the same.

func (AssertableInertia) AssertDeferredProps added in v1.3.5 

func (i AssertableInertia) AssertDeferredProps(want map[string][]string)

AssertDeferredProps verifies that deferred props from Inertia response and the passed deferred props are the same.

func (AssertableInertia) AssertEncryptHistory added in v1.3.5 

func (i AssertableInertia) AssertEncryptHistory(want bool)

AssertEncryptHistory verifies that encrypt history value from Inertia response and the passed value are the same.

func (AssertableInertia) AssertMergeProps added in v1.3.5 

func (i AssertableInertia) AssertMergeProps(want []string)

AssertMergeProps verifies that merge props from Inertia response and the passed merge props are the same.

func (AssertableInertia) AssertProps added in v1.0.2 

func (i AssertableInertia) AssertProps(want Props)

AssertProps verifies that props from Inertia response and the passed props are the same.

func (AssertableInertia) AssertURL added in v1.0.2 

func (i AssertableInertia) AssertURL(want string)

AssertURL verifies that url from Inertia response and the passed url are the same.

func (AssertableInertia) AssertVersion added in v1.0.2 

func (i AssertableInertia) AssertVersion(want string)

AssertVersion verifies that version from Inertia response and the passed version are the same.

type DeferProp added in v1.3.5 

type DeferProp struct {
	Value any
	Group string
	// contains filtered or unexported fields
}

DeferProp is a property that will evaluate after page load.

https://v2.inertiajs.com/deferred-props

func Defer added in v1.3.5 

func Defer(value any, group ...string) DeferProp

func (DeferProp) Merge added in v1.3.5 

func (p DeferProp) Merge() DeferProp

func (DeferProp) Prop added in v1.3.5 

func (p DeferProp) Prop() any

type FlashProvider added in v1.1.8 

type FlashProvider interface {
	FlashErrors(ctx context.Context, errors ValidationErrors) error
	GetErrors(ctx context.Context) (ValidationErrors, error)
	ShouldClearHistory(ctx context.Context) (bool, error)
	FlashClearHistory(ctx context.Context) error
}

FlashProvider defines an interface for a flash data provider.

type Inertia 

type Inertia struct {
	// contains filtered or unexported fields
}

Inertia is a main Gonertia structure, which contains all the logic for being an Inertia adapter.

func New 

func New(rootTemplateHTML string, opts ...Option) (*Inertia, error)

New initializes and returns Inertia.

func NewFromBytes added in v1.1.4 

func NewFromBytes(rootTemplateBs []byte, opts ...Option) (*Inertia, error)

NewFromBytes receive bytes with root template html and then initializes Inertia.

func NewFromFile added in v1.1.3 

func NewFromFile(rootTemplatePath string, opts ...Option) (*Inertia, error)

NewFromFile reads all bytes from the root template file and then initializes Inertia.

func NewFromReader added in v1.1.4 

func NewFromReader(rootTemplateReader io.Reader, opts ...Option) (*Inertia, error)

NewFromReader reads all bytes from the reader with root template html and then initializes Inertia.

func NewFromTemplate added in v1.3.5 

func NewFromTemplate(rootTemplate *template.Template, opts ...Option) (*Inertia, error)

NewFromTemplate receives a *template.Template and then initializes Inertia.

func (*Inertia) Back added in v1.0.5 

func (i *Inertia) Back(w http.ResponseWriter, r *http.Request, status ...int)

Back creates plain redirect response to the previous url.

func (*Inertia) Location 

func (i *Inertia) Location(w http.ResponseWriter, r *http.Request, url string, status ...int)

Location creates redirect response.

If request was made by Inertia - sets status to 409 and url will be in "X-Inertia-Location" header. Otherwise, it will do an HTTP redirect with specified status (default is 302 for GET, 303 for POST/PUT/PATCH).

func (*Inertia) Middleware 

func (i *Inertia) Middleware(next http.Handler) http.Handler

Middleware returns Inertia middleware handler.

All of your handlers that can be handled by the Inertia should be under this middleware.

func (*Inertia) Redirect added in v1.2.0 

func (i *Inertia) Redirect(w http.ResponseWriter, r *http.Request, url string, status ...int)

Redirect creates plain redirect response.

func (*Inertia) Render 

func (i *Inertia) Render(w http.ResponseWriter, r *http.Request, component string, props ...Props) (err error)

Render returns response with Inertia data.

If request was made by Inertia - it will return data in JSON format. Otherwise, it will return HTML with root template.

If SSR is enabled, pre-renders JavaScript and return HTML (https://inertiajs.com/server-side-rendering).

func (*Inertia) ShareProp 

func (i *Inertia) ShareProp(key string, val any)

ShareProp adds passed prop to shared props.

func (*Inertia) ShareTemplateData 

func (i *Inertia) ShareTemplateData(key string, val any)

ShareTemplateData adds passed data to shared template data.

func (*Inertia) ShareTemplateFunc 

func (i *Inertia) ShareTemplateFunc(key string, val any) error

ShareTemplateFunc adds the passed value to the shared template func map. If no root template HTML string has been defined, it returns an error.

func (*Inertia) SharedProp 

func (i *Inertia) SharedProp(key string) (any, bool)

SharedProp return the shared prop.

func (*Inertia) SharedProps 

func (i *Inertia) SharedProps() Props

SharedProps returns shared props.

type JSONMarshaller added in v1.1.6 

type JSONMarshaller interface {
	Marshal(v any) ([]byte, error)
	Decode(r io.Reader, v any) error
}

JSONMarshaller is marshaller which use for marshal/unmarshal JSON.

type LazyProp deprecated 

type LazyProp = OptionalProp

Deprecated: use OptionalProp.

func Lazy deprecated added in v1.3.5 

func Lazy(value any) LazyProp

Deprecated: use Optional.

type Logger added in v1.1.8 

type Logger interface {
	Printf(format string, v ...any)
	Println(v ...any)
}

Logger defines an interface for debug messages.

type MergeProps added in v1.3.5 

type MergeProps struct {
	Value any
	// contains filtered or unexported fields
}

MergeProps is a property, which items will be merged instead of overwrite.

https://v2.inertiajs.com/merging-props

func Merge added in v1.3.5 

func Merge(value any) MergeProps

func (MergeProps) Merge added in v1.3.5 

func (p MergeProps) Merge() MergeProps

func (MergeProps) Prop added in v1.3.5 

func (p MergeProps) Prop() any

type Option 

type Option func(i *Inertia) error

Option is an option parameter that modifies Inertia.

func WithContainerID 

func WithContainerID(id string) Option

WithContainerID returns Option that will set Inertia's container id.

func WithEncryptHistory added in v1.3.5 

func WithEncryptHistory(encryptHistory ...bool) Option

WithEncryptHistory returns Option that will enable Inertia's global history encryption.

func WithFlashProvider added in v1.1.8 

func WithFlashProvider(flash FlashProvider) Option

WithFlashProvider returns Option that will set Inertia's flash data provider.

func WithJSONMarshaller added in v1.1.6 

func WithJSONMarshaller(jsonMarshaller JSONMarshaller) Option

WithJSONMarshaller returns Option that will set Inertia's JSON marshaller.

func WithLogger 

func WithLogger(logs ...Logger) Option

WithLogger returns Option that will set Inertia's logger.

func WithSSR added in v1.1.0 

func WithSSR(url ...string) Option

WithSSR returns Option that will enable server side rendering on Inertia.

func WithVersion 

func WithVersion(version string) Option

WithVersion returns Option that will set Inertia's version.

func WithVersionFromFile added in v1.1.0 

func WithVersionFromFile(path string) Option

WithVersionFromFile returns Option that will set Inertia's version based on file checksum.

type OptionalProp added in v1.3.5 

type OptionalProp struct {
	Value any
	// contains filtered or unexported fields
}

OptionalProp is a property that will evaluate when needed.

https://inertiajs.com/partial-reloads

func Optional added in v1.3.5 

func Optional(value any) OptionalProp

func (OptionalProp) Prop added in v1.3.5 

func (p OptionalProp) Prop() any

type Proper added in v1.1.5 

type Proper interface {
	Prop() any
}

Proper is an interface for custom type, which provides property, that will be resolved.

type Props 

type Props map[string]any

Props are the data that will be transferred and will be available in the front-end component.

func PropsFromContext added in v1.0.5 

func PropsFromContext(ctx context.Context) Props

PropsFromContext returns props from the context.

type TemplateData 

type TemplateData map[string]any

TemplateData are data that will be available in the root template.

func TemplateDataFromContext added in v1.0.5 

func TemplateDataFromContext(ctx context.Context) TemplateData

TemplateDataFromContext returns template data from the context.

type TemplateFuncs added in v1.1.0 

type TemplateFuncs map[string]any

TemplateFuncs are functions that will be available in the root template.

type TryProper added in v1.1.5 

type TryProper interface {
	TryProp() (any, error)
}

TryProper is an interface for custom type, which provides property and error, that will be resolved.

type ValidationErrors added in v1.0.5 

type ValidationErrors map[string]any

ValidationErrors are messages, that will be stored in the "errors" prop.

func ValidationErrorsFromContext added in v1.0.5 

func ValidationErrorsFromContext(ctx context.Context) ValidationErrors

ValidationErrorsFromContext returns validation errors from the context.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.