README
¶
Gonertia
Gonertia is a well-tested and zero-dependency Inertia.js server-side adapter for Golang. Visit inertiajs.com to learn more.
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.
Roadmap
- Tests
- Helpers for testing
- Helpers for validation errors
- SSR
- CLI
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"
"http"
"time"
inertia "github.com/romsar/gonertia"
)
func main() {
i, err := inertia.New("./ui/templates/root.html")
if err != nil {
log.Fatal(err)
}
// Now create your HTTP server.
// Gonertia works well with standard http handlers,
// but you are free to use some frameworks 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 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">
<title>title</title>
{{ .inertiaHead }}
</head>
<body>
{{ .inertia }}
<script src="/static/js/app.js"></script>
</body>
</html>
More examples
Load root template using embed
import "embed"
//go:embed templates
var templateFS embed.FS
// ...
i, err := inertia.New(
/* ... */
inertia.WithTemplateFS(templateFS),
)
Set asset version (learn more)
i, err := inertia.New(
/* ... */
inertia.WithVersion("some-version"), // by any string
inertia.WithAssetURL("/static/js/1f0f8sc6.js"), // by asset url
inertia.WithManifestFile("./ui/manifest.json"), // by manifest file
)
Replace standard JSON marshall function
import jsoniter "github.com/json-iterator/go"
// ...
i, err := inertia.New(
/* ... */,
inertia.WithMarshalJSON(jsoniter.Marshal),
)
Use your logger
i, err := inertia.New(
/* ... */
inertia.WithLogger(somelogger.New()),
// or inertia.WithoutLogger(),
)
Set custom container id
i, err := inertia.New(
/* ... */
inertia.WithContainerID("inertia"),
)
Closure and lazy props (learn more)
props := inertia.Props{
"regular": "prop",
"closure": func () (any, error) { return "prop", nil },
"lazy": inertia.LazyProp(func () (any, error) {
return "prop", nil
},
}
i.Render(w, r, "Some/Page", props)
Redirects (learn more)
func homeHandler(i *inertia.Inertia) http.Handler {
fn := func(w http.ResponseWriter, r *http.Request) {
i.Location(w, r, "/some-url")
}
return http.HandlerFunc(fn)
}
NOTES: If response is empty - user will be redirected to the previous url.
To redirect back, you can use Back helper:
i.Back(w, r)
Share template data (learn more)
i.ShareTemplateData("title", "Home page")
<title>{{ .title }}</title>
Share template func
i.ShareTemplateFunc("trim", strings.Trim)
<title>{{ trim "foo bar" }}</title>
Pass template data via context (in middleware)
ctx := i.WithTemplateData(r.Context(), "title", "Home page")
// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).
Share prop globally (learn more)
i.ShareProp("name", "Roman")
Pass props via context (in middleware)
ctx := i.WithProp(r.Context(), "name", "Roman")
// or i.WithProps(r.Context(), inertia.Props{"name": "Roman"})
// pass it to the next middleware or inertia.Render function using r.WithContext(ctx).
Validation errors (learn more)
ctx := i.WithValidationError(r.Context(), "some_field", "some error")
// or i.WithValidationErrors(r.Context(), inertia.ValidationErrors{"some_field": "some error"})
// 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.Assert(t, body) // io.Reader body
// OR
assertable := inertia.AssertFromBytes(t, body) // []byte body
// OR
assertable := inertia.AssertFromString(t, body) // 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"}
}
Credits
This package is based on inertiajs/inertia-laravel and uses some parts of petaki/inertia-go.
License
Gonertia is released under the MIT License.
Documentation
¶
Index ¶
- func IsInertiaRequest(r *http.Request) bool
- type AssertableInertia
- type Inertia
- func (i *Inertia) Back(w http.ResponseWriter, r *http.Request, status ...int)
- func (i *Inertia) FlushSharedProps()
- func (i *Inertia) FlushSharedTemplateData()
- func (i *Inertia) FlushSharedTemplateFuncs()
- func (i *Inertia) Location(w http.ResponseWriter, r *http.Request, url string, status ...int)
- func (i *Inertia) Middleware(next http.Handler) http.Handler
- func (i *Inertia) Render(w http.ResponseWriter, r *http.Request, component string, props ...Props) (err error)
- func (i *Inertia) ShareProp(key string, val any)
- func (i *Inertia) ShareTemplateData(key string, val any)
- func (i *Inertia) ShareTemplateFunc(key string, val any)
- func (i *Inertia) SharedProp(key string) (any, bool)
- func (i *Inertia) SharedProps() Props
- func (i *Inertia) WithProp(ctx context.Context, key string, val any) context.Context
- func (i *Inertia) WithProps(ctx context.Context, props Props) context.Context
- func (i *Inertia) WithTemplateData(ctx context.Context, key string, val any) context.Context
- func (i *Inertia) WithValidationError(ctx context.Context, key string, msg any) context.Context
- func (i *Inertia) WithValidationErrors(ctx context.Context, errors ValidationErrors) context.Context
- type LazyProp
- type Option
- func WithAssetURL(url string) Option
- func WithContainerID(id string) Option
- func WithLogger(log logger) Option
- func WithManifestFile(path string) Option
- func WithMarshalJSON(f marshallJSON) Option
- func WithTemplateFS(templateFS fs.FS) Option
- func WithVersion(version string) Option
- func WithoutLogger() Option
- type Props
- type TemplateData
- type ValidationErrors
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsInertiaRequest ¶
IsInertiaRequest returns true if the request is an Inertia request.
Types ¶
type AssertableInertia ¶ added in v1.0.2
type AssertableInertia struct {
// contains filtered or unexported fields
}
AssertableInertia is an Inertia response struct with assert methods.
func Assert ¶ added in v1.0.4
func Assert(t t, body io.Reader) AssertableInertia
Assert creates AssertableInertia from the io.Reader body.
func AssertFromBytes ¶ added in v1.0.4
func AssertFromBytes(t t, body []byte) AssertableInertia
AssertFromBytes creates AssertableInertia from the bytes body.
func AssertFromString ¶ added in v1.0.4
func AssertFromString(t t, body string) AssertableInertia
AssertFromString creates AssertableInertia from the string body.
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) 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 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 (*Inertia) FlushSharedProps ¶
func (i *Inertia) FlushSharedProps()
FlushSharedProps flushes shared props.
func (*Inertia) FlushSharedTemplateData ¶
func (i *Inertia) FlushSharedTemplateData()
FlushSharedTemplateData flushes shared template data.
func (*Inertia) FlushSharedTemplateFuncs ¶ added in v1.0.1
func (i *Inertia) FlushSharedTemplateFuncs()
FlushSharedTemplateFuncs flushes the shared template func map.
func (*Inertia) Location ¶
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 ¶
Middleware returns Inertia middleware handler.
All of your handlers that can be handled by the Inertia should be under this middleware.
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.
func (*Inertia) ShareTemplateData ¶
ShareTemplateData adds passed data to shared template data.
func (*Inertia) ShareTemplateFunc ¶
ShareTemplateFunc adds passed value to the shared template func map.
func (*Inertia) SharedProp ¶
SharedProp return the shared prop.
func (*Inertia) SharedProps ¶
SharedProps returns shared props.
func (*Inertia) WithTemplateData ¶
WithTemplateData appends template data value to the passed context.Context.
func (*Inertia) WithValidationError ¶ added in v1.0.5
WithValidationError appends validation error to the passed context.Context.
func (*Inertia) WithValidationErrors ¶ added in v1.0.5
func (i *Inertia) WithValidationErrors(ctx context.Context, errors ValidationErrors) context.Context
WithValidationErrors appends validation errors to the passed context.Context.
type Option ¶
Option is an option parameter that modifies Inertia.
func WithAssetURL ¶
WithAssetURL returns Option that will set Inertia's version based on asset url.
func WithContainerID ¶
WithContainerID returns Option that will set Inertia's container id.
func WithLogger ¶
func WithLogger(log logger) Option
WithLogger returns Option that will set Inertia's logger.
func WithManifestFile ¶
WithManifestFile returns Option that will set Inertia's version based on manifest file.
func WithMarshalJSON ¶
func WithMarshalJSON(f marshallJSON) Option
WithMarshalJSON returns Option that will set Inertia's marshallJSON func.
func WithTemplateFS ¶
WithTemplateFS returns Option that will set Inertia's templateFS.
func WithVersion ¶
WithVersion returns Option that will set Inertia's version.
func WithoutLogger ¶
func WithoutLogger() Option
WithoutLogger returns Option that will unset Inertia's logger. Actually set a logger with io.Discard output.
type Props ¶
Props are the data that will be transferred and will be available in the front-end component.
type TemplateData ¶
TemplateData are the data that will be transferred and will be available in the root template.
func TemplateDataFromContext ¶ added in v1.0.5
func TemplateDataFromContext(ctx context.Context) (TemplateData, error)
TemplateDataFromContext returns template data from the context.
type ValidationErrors ¶ added in v1.0.5
ValidationErrors are messages, that will be stored in the "errors" prop.
func ValidationErrorsFromContext ¶ added in v1.0.5
func ValidationErrorsFromContext(ctx context.Context) (ValidationErrors, error)
ValidationErrorsFromContext returns validation errors from the context.
Source Files