gospa

GoSPA

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

(pushing to main/master will stop upon either i feel like it or other people start using or developing)

Features

• Reactive Primitives — Rune[T], Derived[T], Effect - Svelte-like reactivity in Go
• High-Performance Serialization — Integrated goccy/go-json (2-3x faster) and optional binary MessagePack support
• File-Based Routing — SvelteKit-style routing for .templ files
• WebSocket Sync — Real-time client-server state synchronization with GZIP compression and delta-only patching
• Session Management — Secure session persistence with SessionStore and ClientStateStore
• Type Safety — Compile-time template validation with Templ
• Lightweight Runtime — ~15KB default runtime (trusts server), ~35KB secure runtime with DOMPurify for user-generated content.
• Remote Actions — Type-safe server functions callable directly from the client.
• Middleware & Error Boundaries — File-based _middleware.go and _error.templ for segment-scoped logic and error handling.
• Rendering Modes — Mix SSR, SSG, ISR, and PPR per-page rendering strategies.
• Rate Limiting — Configurable connection and per-route rate limiters.
• Structured Logging — Integrated slog for modern structured JSON/Text logging.
• Security — Built-in CSRF protection, customizable CORS origins, and strict XSS prevention with optional DisableSanitization for trusted content.

Installation

go get github.com/aydenstechdungeon/gospa

Quick Start

1. Initialize Project

go install github.com/aydenstechdungeon/gospa/cmd/gospa@latest
gospa create myapp
cd myapp
go mod tidy

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",
        SerializationFormat: "msgpack", // use binary serialization for speed
        CompressState:       true,      // enable GZIP for state updates
    })

    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

gospa generate
go run .

or

gospa dev

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
├ _middleware.go       → Global middleware
├ _error.templ         → Global error boundary
├ _loading.templ       → Global loading shell (for PPR)
├ page.templ           → /
├ about/
│   └ page.templ       → /about
├ (auth)/              → Grouped routes
│   ├ layout.templ
│   ├ _middleware.go   → Middleware only for (auth) routes
│   ├ login/
│   │   └ page.templ   → /login
│   └ register/
│       └ page.templ   → /register
├ blog/
│   ├── layout.templ   → Layout for /blog/*
│   ├── _error.templ   → Error boundary for /blog/*
│   └ [id]/
│       └ page.templ   → /blog/:id
└ posts/
    └ [...rest]/
        └ page.templ   → /posts/* (catch-all)

Special Routing Files

• page.templ — Renders the page component for a route directory.
• layout.templ — Wraps nested child pages.
• _middleware.go — Segment-scoped middleware intercepting requests before they hit pages.
• _error.templ — Nearest error boundary. If a page panics or errors during SSR, it falls back to this.
• _loading.templ — Automatically compiled into the PPR static shell for pages without custom dynamic shells.

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())
})

// Remote action helper
GoSPA.remote('saveData', { count: count.get() })

Runtime Variants: Default vs Secure

GoSPA follows a "trust the server" security model (similar to SvelteKit). The default runtime trusts server-rendered HTML because Templ auto-escapes all dynamic content.

Default Runtime (gospa) — Recommended for most apps:

import { init } from '@gospa/client';
init(); // ~15KB, no sanitizer needed

Secure Runtime (gospa/runtime-secure) — For user-generated content:

import { init, sanitize } from '@gospa/client/runtime-secure';
init(); // ~35KB, includes DOMPurify

// Sanitize user-generated HTML
const clean = await sanitize(userComment);

When do you need the secure runtime?

• User comments with HTML formatting
• Forums, wikis, social media apps
• Rich text editors (WYSIWYG)
• Any user-generated HTML content

When is the default runtime sufficient?

• Server-rendered Templ templates
• Text content from your database
• JSON data
• Any content already escaped by Templ on the server

See docs/03-features/01-client-runtime.md for the complete runtime selection guide.

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.

import (
    "context"
    "github.com/aydenstechdungeon/gospa/routing"
)

// Register on server
routing.RegisterRemoteAction("saveData", func(ctx context.Context, rc routing.RemoteContext, input interface{}) (interface{}, error) {
    // rc.IP, rc.Headers, rc.UserAgent gives robust contextual connection information

    // Type assert input to access data
    data, ok := input.(map[string]interface{})
    if !ok {
        return nil, errors.New("invalid input")
    }
    
    // Process data securely on the server
    id, _ := data["id"].(float64) // JSON numbers parse as float64
    
    return map[string]interface{}{
        "status": "success",
        "id":     int(id),
    }, nil
})

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

// Call from client
import { remote } from '@gospa/client';

const result = await remote('saveData', { id: 123 });

if (result.ok) {
    console.log('Success:', result.data);
} else {
    console.error('Error:', result.error, 'Code:', result.code);
    // Handle specific error codes programmatically
}

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{
    // ...
    AllowedOrigins: []string{"https://myapp.com", "https://api.myapp.com"},
})

Security By Default: CSRF protection is enabled by default (EnableCSRF: true), and GoSPA automatically wires both the token issuer and validator middlewares for you. The built-in client remote helper sends the X-CSRF-Token header automatically for same-origin requests.

Rendering Strategies

GoSPA supports four per-page rendering strategies:

Select a strategy per-page in your init():

import (
    "time"
    "github.com/aydenstechdungeon/gospa/routing"
)

func init() {
    // ISR: serve stale, revalidate in background every 5 minutes
    routing.RegisterPageWithOptions("/pricing", pricingPage, routing.RouteOptions{
        Strategy:        routing.StrategyISR,
        RevalidateAfter: 5 * time.Minute,
    })

    // PPR: cache nav/footer shell, re-render feed slot per-request
    routing.RegisterPageWithOptions("/dashboard", dashboardPage, routing.RouteOptions{
        Strategy:     routing.StrategyPPR,
        DynamicSlots: []string{"feed"},
    })
    routing.RegisterSlot("/dashboard", "feed", feedSlot)
}

Enable caching in your app config:

app := gospa.New(gospa.Config{
    CacheTemplates:         true,
    DefaultRenderStrategy:  routing.StrategyISR,  // app-wide fallback
    DefaultRevalidateAfter: 10 * time.Minute,
})

See docs/02-core-concepts/02-rendering.md for full rendering documentation.

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
│   ├── root_layout.templ  # Root HTML shell (optional)
│   ├── layout.templ       # Root-level layout (optional)
│   ├── page.templ         # Home page
│   └ about/
│       └ page.templ
├ components/          # Reusable .templ components (optional)
├ lib/                 # Shared Go code (optional)
│   └ state.go         # App state
├ main.go
└ go.mod

Layout Files

GoSPA supports two types of layout files:

root_layout.templ — The outermost wrapper for your app. Must include the HTML document structure and GoSPA runtime script. There can only be one root layout (at routes/root_layout.templ). Requires routing.RegisterRootLayout().

layout.templ — Regular layouts that wrap pages within a route segment. You can have multiple nested layouts (e.g., routes/blog/layout.templ wraps all /blog/* pages).

routes/
├── root_layout.templ     # (Optional) Wraps entire app (Requires routing.RegisterRootLayout())
├── layout.templ          # Optional root-level layout
├── page.templ            # Home page (/)
├── about/
│   └── page.templ        # About page (/about)
└── blog/
    ├── layout.templ      # Wraps all blog pages
    └── page.templ        # Blog index (/blog)

If no root_layout.templ exists, GoSPA provides a minimal default HTML wrapper.

API Reference

See docs/04-api-reference/ 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 (for example gospa build --help) to see all available options and flags.

For more details, see docs/04-api-reference/03-cli.md.

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]
    widths: [320, 640, 1280, 1920]
  auth:
    jwt_secret: ${JWT_SECRET}
    oauth_providers: [google]
    google_client_id: ${GOOGLE_CLIENT_ID}
    google_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

The current repository documents the built-in plugin model only. Dynamic plugin installation and external shared-library loading are not part of the checked-in CLI surface.

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", Alias: "mp", Description: "Run my plugin"},
    }
}

See docs/04-api-reference/04-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