gospa

GoSPA

A Go framework for building reactive SPAs with server-side rendering. Brings Svelte-like reactivity to Go using Fiber and Templ.

Features

• Reactive Primitives — Rune[T], Derived[T], Effect - Svelte-like reactivity in Go
• File-Based Routing — SvelteKit-style routing for .templ files
• WebSocket Sync — Real-time client-server state synchronization
• Session Management — Secure session persistence with SessionStore and ClientStateStore
• Type Safety — Compile-time template validation with Templ
• Lightweight Runtime — ~11KB for the simple runtime, ~17KB for the full runtime with DOMPurify.
• Remote Actions — Type-safe server functions callable directly from the client.
• Security — Built-in CSRF protection, customizable CORS origins, and strict XSS prevention.
• Rendering Modes — Seamlessly mix CSR, SSR, and SSG per-page rendering strategies.

Installation

go get github.com/aydenstechdungeon/gospa

Quick Start

1. Initialize Project

go run github.com/aydenstechdungeon/gospa/cmd/gospa@latest create myapp

or from examples/:

go run ../cmd/gospa create myapp

from inside a examples project:

go run ../../cmd/gospa create myapp

mkdir myapp && cd myapp
go mod init myapp

2. Create Main File

// main.go
package main

import (
    "log"
    _ "myapp/routes" // Import routes to trigger init()
    
    "github.com/aydenstechdungeon/gospa"
)

func main() {
    app := gospa.New(gospa.Config{
        RoutesDir: "./routes",
        DevMode:   true,
        AppName:   "myapp",
    })

    if err := app.Run(":3000"); err != nil {
        log.Fatal(err)
    }
}

3. Create a Page

// routes/page.templ
package routes

templ Page() {
    <div data-gospa-component="counter" data-gospa-state='{"count":0}'>
        <h1>Counter</h1>
        <span data-bind="text:count">0</span>
        <button data-on="click:increment">+</button>
        <button data-on="click:decrement">−</button>
    </div>
}

4. Run

go run main.go

Core Concepts

State Modes

GoSPA supports two state management modes:

Local State (Client-Only)

State lives entirely in the browser. No server synchronization.

<div data-gospa-component="counter" data-gospa-local>
    <span data-bind="text:count">0</span>
    <button data-on="click:increment">+</button>
</div>

Synced State (Client-Server)

State synchronizes across all connected clients via WebSocket.

// Server-side handler with broadcast
fiber.RegisterActionHandler("increment", func(client *fiber.WSClient, payload json.RawMessage) {
    GlobalCounter.Count++
    fiber.BroadcastState(hub, "count", GlobalCounter.Count)
})

Reactive Primitives

Rune[T] — Reactive State

count := state.NewRune(0)
count.Get()           // 0
count.Set(5)          // notifies subscribers
count.Update(func(v int) int { return v + 1 })

Derived[T] — Computed State

count := state.NewRune(5)
doubled := state.NewDerived(func() int {
    return count.Get() * 2
})
doubled.Get() // 10

Effect — Side Effects

cleanup := state.NewEffect(func() func() {
    fmt.Println("Count:", count.Get())
    return func() { fmt.Println("cleanup") }
})
defer cleanup()

File-Based Routing

routes/
├ root_layout.templ    → Base HTML shell
├ page.templ           → /
├ about/
│   └ page.templ       → /about
├ blog/
│   ├── layout.templ   → Layout for /blog/*
│   └ [id]/
│       └ page.templ   → /blog/:id
└ posts/
    └ [...rest]/
        └ page.templ   → /posts/* (catch-all)

Embedded Routes (Production)

For production, you can embed your routes into the binary using go:embed. This allows for a zero-dependency, single-binary distribution.

// prod.go
//go:embed routes/*
var embeddedRoutes embed.FS

// main.go
var routesFS fs.FS
if devMode {
    routesFS = os.DirFS("./routes") // Real files for hot-reloading
} else {
    // Use the embedded files for production
    sub, _ := fs.Sub(embeddedRoutes, "routes")
    routesFS = sub
}

app := gospa.New(gospa.Config{
    RoutesFS: routesFS,
    DevMode:  devMode,
    // ...
})

Client Runtime

// Initialize component
GoSPA.init({ wsUrl: 'ws://localhost:3000/_gospa/ws' })

// Reactive state
const count = new GoSPA.Rune(0)
const doubled = new GoSPA.Derived(() => count.get() * 2)

// Effects
new GoSPA.Effect(() => {
    console.log('Count:', count.get())
})

// DOM binding
GoSPA.bindElement('element-id', count)

// Navigation
GoSPA.navigate('/about')
GoSPA.prefetch('/blog')

// Transitions
GoSPA.fade(element, { duration: 300 })

Performance vs Security (Simple Runtime)

By default, the client runtime includes DOMPurify for robust XSS protection on dynamically bound templates. If you prefer a smaller bundle size and are comfortable with a less strictly-secured basic sanitizer, you can switch to the lightweight runtime using the configuration flag:

app := gospa.New(gospa.Config{
    // ...
    SimpleRuntime: true, 
})

Remote Actions

Remote Actions allow you to Define type-safe server functions that can be invoked seamlessly from the client without manually managing HTTP endpoints.

// Register on server
routing.RegisterRemoteAction("saveData", func(ctx context.Context, input interface{}) (interface{}, error) {
    // Process data securely on the server
    return map[string]string{"status": "success"}, nil
})

// Configure endpoint restrictions
app := gospa.New(gospa.Config{
    RemotePrefix:       "/api/rpc",
    MaxRequestBodySize: 1024 * 1024, // Limit body to 1MB
})

// Call from client
const result = await GoSPA.callAction('saveData', { id: 123 });

Application Security

GoSPA comes with secure defaults, but robust configurations exist for production use to secure cross-origin requests and mitigate CSRF attacks:

app := gospa.New(gospa.Config{
    // ...
    EnableCSRF: true,
    AllowedOrigins: []string{"https://myapp.com", "https://api.myapp.com"},
})

Partial Hydration

Opt out of reactivity for static content:

<div data-gospa-static>
    <h1>Static content — no bindings or event listeners</h1>
</div>

Transitions

<div data-transition="fade" data-transition-params='{"duration": 300}'>
    Fades in and out
</div>

<div data-transition-in="fly" data-transition-out="slide">
    Different enter/exit animations
</div>

Project Structure

myapp/
├ routes/              # Auto-routed .templ files
│   ├── page.templ
│   └ about/
│       └ page.templ
├ components/          # Reusable .templ components
├ lib/                 # Shared Go code
│   └ state.go         # App state
├ main.go
└ go.mod

API Reference

See docs/API.md for complete API documentation.

CLI

gospa create myapp    # Create new project
gospa generate        # Generate types and routes
gospa dev             # Development server with hot reload
gospa build           # Production build

Run any command with --help (e.g., gospa build --help) to see all available options and flags.

For more details, see the CLI Reference.

Plugin Ecosystem

GoSPA includes a powerful plugin system for extending build and development workflows.

Built-in Plugins

Configuration

Plugins are configured in gospa.yaml:

plugins:
  tailwind:
    input: ./styles/main.css
    output: ./static/css/output.css
  image:
    input: ./images
    output: ./static/images
    formats: [webp, jpeg]
    sizes: [320, 640, 1280, 1920]
  auth:
    jwt_secret: ${JWT_SECRET}
    oauth:
      google:
        client_id: ${GOOGLE_CLIENT_ID}
        client_secret: ${GOOGLE_CLIENT_SECRET}

Plugin Hooks

Plugins integrate at key lifecycle points:

• BeforeGenerate / AfterGenerate — Code generation
• BeforeDev / AfterDev — Development server
• BeforeBuild / AfterBuild — Production build

Creating Custom Plugins

package myplugin

import "github.com/aydenstechdungeon/gospa/plugin"

type MyPlugin struct{}

func (p *MyPlugin) Name() string { return "my-plugin" }
func (p *MyPlugin) Init() error { return nil }
func (p *MyPlugin) Dependencies() []plugin.Dependency {
    return []plugin.Dependency{
        {Name: "some-go-package", Type: plugin.DepGo},
        {Name: "some-bun-package", Type: plugin.DepBun},
    }
}
func (p *MyPlugin) OnHook(hook plugin.Hook, ctx map[string]interface{}) error {
    // Handle lifecycle hooks
    return nil
}
func (p *MyPlugin) Commands() []plugin.Command {
    return []plugin.Command{
        {Name: "my-plugin:run", Short: "mp", Description: "Run my plugin"},
    }
}

See docs/PLUGINS.md for complete plugin documentation.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Browser                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              GoSPA Runtime (<15KB*)                   │    │
│  │  ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │    │
│  │  │  Rune   │ │ Derived  │ │ Effect  │ │WebSocket │ │    │
│  │  └────┬────┘ └────┬─────┘ └────┬────┘ └────┬─────┘ │    │
│  │       └───────────┴────────────┴──────────┘        │    │
│  │                      │                              │    │
│  │              ┌───────┴───────┐                     │    │
│  │              │  DOM Binder   │                     │    │
│  │              └───────────────┘                     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                               │
                               │ WebSocket / HTTP
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                       Go Server                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    Fiber App                         │    │
│  │  ┌──────────────┐  ┌──────────────┐                 │    │
│  │  │   Runtime    │  │   WebSocket  │                 │    │
│  │  │  Middleware  │  │   Handler    │                 │    │
│  │  └──────────────┘  └──────────────┘                 │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                  State Package                       │    │
│  │  ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │    │
│  │  │  Rune   │ │ Derived  │ │ Effect  │ │  Batch   │ │    │
│  │  └─────────┘ └──────────┘ └─────────┘ └──────────┘ │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Comparison

License

Apache License 2.0