README
¶
Gothic Framework — Core (runtime library)
Gothic Framework is a developer-first toolset for building fast, scalable, modern web apps in Go with the GOTTH stack — Go, TailwindCSS, Templ, and HTMX.
This module (github.com/gothicframework/core) is the runtime library a Gothic app imports: file-based routing, the caching/ISR layer, the client-side WASM runtime, and the framework's HTTP assets. It has no CLI and no cloud/deploy dependencies — a project importing core never pulls in Docker or the AWS SDK.
You don't add
coreto a project by hand. Install thegothicCLI and rungothic init— it scaffolds a project that importscore(pluscomponentsandmiddlewares) at the right versions.go install github.com/gothicframework/cli/v3/cmd/gothic@latest gothic init github.com/you/my-app
What's inside
| Package | Import path | Role |
|---|---|---|
config |
github.com/gothicframework/core/config |
The gothic.config.go schema: Config, DeployConfig, RuntimeConfig, the ENV builders (Env/SSMParam/SecretsManager), and the deploy Provider enum. |
router |
github.com/gothicframework/core/router |
File-based routing, RouteConfig[T] / ApiRouteConfig, and the cache backends (in-memory / Redis / local-files) that power static caching + ISR. |
wasm |
github.com/gothicframework/core/wasm |
The client-side state runtime — ClientSideState, observables, topics, durable cache — compiled per-component to TinyGo WASM, plus the static full-Go core. The static core also embeds the Go/WASM htmx runtime (htmx-go), which installs window.htmx on boot, so gothic-core.wasm provides the page's htmx client. |
runtimeassets |
github.com/gothicframework/core/runtimeassets |
Serves the framework's browser runtime from an embed under /_gothic/* — the five assets gothic-core.js, gothic-core.wasm, gothic-core-exec.js, gothic-core-boot.js, and wasm_exec.js (precompressed brotli+gzip, content-negotiated). |
render |
github.com/gothicframework/core/render |
Templ render cache + logger used by the router. |
gothiccore · corewasm · wasmexec |
…/core/{gothiccore,corewasm,wasmexec} |
The embedded browser assets (gothic-core.js, the prebuilt core.wasm, and the TinyGo wasm_exec.js), each content-hash versioned for cache-busting. |
The reusable UI components and the runtime middleware live in the companion modules, so the pieces you write into pages come from there:
components—RuntimeScripts,Styles,StatefulComponentOf,OptimizedImage.middlewares—middlewares.Middleware, the single chi middleware that wires the whole runtime.
How a Gothic app uses it
A scaffolded project mounts the entire runtime as one chi middleware and pulls the runtime scripts/styles into its layout — the framework's built-in routes (/_gothic/*, /public/*, /optimizedImage/*) all come from that:
// main.go
router := chi.NewMux()
router.Use(middlewares.Middleware(Config.Runtime)) // the entire Gothic runtime
routes.RegisterFileBasedRoutes(router) // your file-based pages
// layout.templ — in <head>
@gothicComponents.Styles()
@gothicComponents.RuntimeScripts()
Configuration is a type-safe gothic.config.go that imports core/config. See the CLI README for the full config schema, the gothic command reference, and deploys.
Design docs
docs/DESIGN-INSPIRATIONS.md— prior art that shaped the v3 design, and what we deliberately did not adopt.docs/adr/— Architecture Decision Records (custom codec, schema seam, two-tier protocol, static full-Go core).RELEASE_NOTES_v3.md— the v3.0.0 breaking-change and feature notes.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config defines the shared, user-facing types used inside a project's gothic.config.go file: the typed environment-value builders (Env, SSMParam, SecretsManager) and the GothicContext passed to lifecycle hooks.
|
Package config defines the shared, user-facing types used inside a project's gothic.config.go file: the typed environment-value builders (Env, SSMParam, SecretsManager) and the GothicContext passed to lifecycle hooks. |
|
Package corewasm owns the Gothic Framework STATIC CORE artifact: the prebuilt, type-agnostic RPC/registration hub compiled with the framework's pinned TinyGo fork.
|
Package corewasm owns the Gothic Framework STATIC CORE artifact: the prebuilt, type-agnostic RPC/registration hub compiled with the framework's pinned TinyGo fork. |
|
Package gothiccore owns gothic-core.js: the shared, idempotent client runtime globals that used to be inlined into every per-instance WASM bootstrap script.
|
Package gothiccore owns gothic-core.js: the shared, idempotent client runtime globals that used to be inlined into every per-instance WASM bootstrap script. |
|
Package templ provides a content-hash cache for .templ files so that `templ generate` is only invoked for files whose contents (or generated counterparts) have changed since the last run.
|
Package templ provides a content-hash cache for .templ files so that `templ generate` is only invoked for files whose contents (or generated counterparts) have changed since the last run. |
|
Package runtimeassets is the single registry + HTTP handler for the Gothic framework's WASM-runtime assets that used to be COPIED into every project's public/ folder at `gothic init` / build time.
|
Package runtimeassets is the single registry + HTTP handler for the Gothic framework's WASM-runtime assets that used to be COPIED into every project's public/ folder at `gothic init` / build time. |
|
Package wasm provides server-side stubs for the WASM reactive runtime.
|
Package wasm provides server-side stubs for the WASM reactive runtime. |
|
core-runtime
command
Command core-runtime is the Gothic Framework full-Go STATIC CORE: a prebuilt, type-agnostic RPC / registration hub.
|
Command core-runtime is the Gothic Framework full-Go STATIC CORE: a prebuilt, type-agnostic RPC / registration hub. |
|
core-runtime/protocol
Package protocol holds the PURE, host-testable decision logic of the Gothic full-Go static core's control plane.
|
Package protocol holds the PURE, host-testable decision logic of the Gothic full-Go static core's control plane. |
|
internal/parity
This file is a byte-identical copy of pkg/wasm/wasm-runtime/runtime/codec.go used by codec_parity_test.go to validate that the server-side stub in pkg/wasm/stubs.go and the WASM-side runtime stay in sync.
|
This file is a byte-identical copy of pkg/wasm/wasm-runtime/runtime/codec.go used by codec_parity_test.go to validate that the server-side stub in pkg/wasm/stubs.go and the WASM-side runtime stay in sync. |
Click to show internal directories.
Click to hide internal directories.