GoSPA

GoSPA (Go Spa and Go S-P-A are the only valid pronunciations) brings Svelte-like reactive primitives (Runes, Effects, Derived) to the Go ecosystem. It is a high-performance framework for building reactive SPAs with Templ, Fiber, file-based routing, and real-time state synchronization.

Highlights

• Native Reactivity - Rune, Derived, Effect primitives that work exactly like Svelte 5.
• WebSocket Sync - Transparent client-server state synchronization with GZIP delta patching.
• SFC System - Single File Components (.gospa) with scoped CSS and Go-based logic.
• File-Based Routing - SvelteKit-style directory structure for .templ and .gospa files.
• Hybrid Rendering - Mix SSR, SSG, ISR, and PPR on a per-page basis.
• Type-Safe RPC - Call server functions directly from the client without boilerplate endpoints.
• High Performance - Integrated go-json and optional MessagePack for minimal overhead.

Quick Start

0. Prerequisites

• Go 1.25.0+ (matches go.mod; use a current stable toolchain)
• Node.js Tooling: Bun is preferred for the client-side build process (zero-config JS bundling, CSS extraction). pnpm and npm are supported as fallbacks using esbuild, but Bun remains the recommended choice for maximum performance.
• JWT_SECRET: Ensure this environment variable is set for production authentication contexts (when using the Auth plugin).

1. Install CLI

go install github.com/aydenstechdungeon/gospa/cmd/gospa@latest

or

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

2. Scaffold & Run

gospa create myapp
cd myapp
go mod tidy
gospa doctor
gospa dev

or

go run github.com/aydenstechdungeon/gospa/cmd/gospa@latest create myapp
cd myapp
go mod tidy
go run github.com/aydenstechdungeon/gospa/cmd/gospa@latest doctor
go run github.com/aydenstechdungeon/gospa/cmd/gospa@latest dev

For local client/runtime tooling, Bun is strongly preferred. The GoSPA CLI provides fallbacks for pnpm and npm using esbuild, but Bun's integrated bundler is the authoritative development target.

3. A Simple SFC

(.gospa is in alpha, try to use templs instead)

// islands/Counter.gospa
<script lang="go">
  var count = $state(0)
  func increment() { count++ }
</script>

<template>
  <button on:click={increment}>
    Count is {count}
  </button>
</template>

<style>
  button { padding: 1rem; border-radius: 8px; }
</style>

GoSPA automatically compiles this to a reactive Templ component and a TypeScript hydration island.

Comparison

Recommended Production Baseline

Start from gospa.ProductionConfig() and tighten only what your app needs:

config := gospa.ProductionConfig()
config.AllowedOrigins = []string{"https://example.com"}
config.AppName = "myapp"

For prefork deployments, add external Storage and PubSub backends so state and realtime traffic stay consistent across workers.

Security

• Vulnerability scanning (Go): run govulncheck ./... regularly; the repo's GitHub Actions workflow runs tests and govulncheck. For a full local gate, use ./scripts/quality-check.sh.
• Auth plugin: set JWT_SECRET in production. Production is inferred from GOSPA_ENV, ENV / APP_ENV / GO_ENV, or legacy GIN_MODE—see Security.
• CSP: the compatibility default (fiber.DefaultContentSecurityPolicy) allows inline scripts and styles for typical GoSPA output. For tighter deployments, start from fiber.StrictContentSecurityPolicy and set ContentSecurityPolicy explicitly.
• SFC trust boundary: .gospa files are source code, not user content. The compiler embeds <script> blocks directly into generated Go source. Never compile untrusted tenant-provided SFCs in a shared CI or runtime. For semi-trusted sources, enable SafeMode on CompileOptions—see SFC docs.

Documentation

• Browse: gospa.onrender.com/docs (website)
• Authoritative Markdown: docs/README.md (table of contents for the docs/ tree)
• Config & API: docs/configuration.md, docs/api/core.md
• Production: Production checklist, Security
• Examples & Benchmarks: GospaSvKitBenchmark [not complete]

Community & Support

• Discussions: GitHub Discussions
• Issues: GitHub Issues

Apache License 2.0