README
¶
Gothic Framework — Components
Reusable Templ components for Gothic Framework apps. (The one-line runtime middleware now lives in github.com/gothicframework/middlewares.)
github.com/gothicframework/components
Add it to a Gothic project:
go get github.com/gothicframework/components
This module builds on the core runtime (github.com/gothicframework/core) — it depends on core's router (RouteConfig, HttpMethod), config (RuntimeConfig), runtimeassets, gothiccore, and corewasm packages, plus go-chi/chi/v5. It exposes a single importable piece:
- package
gothicComponents(module root) — the layout + UI component catalogue.
The one-line runtime chi middleware that used to live here now ships in its own module, github.com/gothicframework/middlewares — see its README for middlewares.Middleware.
gothicComponents — component catalogue
import gothicComponents "github.com/gothicframework/components"
RuntimeScripts() → templ.Component
Emits the two framework client-runtime <script> tags for the layout <head>:
gothic-core.js— shared, idempotent client-runtime globals (one per page).gothic-core-boot.js— boot loader for the static WASM core.
With these in the <head>, the page has a working htmx: the core installs window.htmx and processes hx-* attributes as it boots, so htmx attributes and the window.htmx API are available with no additional script tag and no CDN request. Third-party htmx extensions can still be loaded as ordinary <script> tags.
On AWS (GOTHIC_PROVIDER=AWS), the component also emits a <meta name="gothic-provider" content="AWS"> marker. The Go/WASM core reads it at boot and signs every htmx request with the SigV4 body hash header x-amz-content-sha256 automatically — no hx-ext and no configuration required. Off AWS the marker is absent and signing is inactive.
The scripts are served from the framework embed at the /_gothic/ route (registered by middlewares.Middleware), so the framework owns them rather than your public/ folder, and their ?v= content-hash cache-busters derive from gothiccore.Version() / corewasm.Version() to stay in sync with the framework version. Place RuntimeScripts in the layout <head>, before any per-instance WASM bootstrap.
Styles() → templ.Component
Emits <link rel="stylesheet" href="/public/styles.css"/>. The styles.css file itself is your Tailwind output and stays in public/ (generated by gothic css); this component is a convenience so the layout references it through the framework, matching how RuntimeScripts is emitted.
StatefulComponentOf[T](config *router.RouteConfig[T], vals ...StatefulComponentData) → templ.Component
Renders a self-loading HTMX wrapper for a Gothic route — a <div> with hx-trigger="load" and hx-swap="outerHTML" whose verb (hx-get/hx-post/hx-put/hx-patch/hx-delete) is taken from the route's HttpMethod and whose URL is the route's Path. It fetches and swaps itself in on load, giving you a component that hydrates from its own endpoint.
StatefulComponentData is map[string]any; pass an optional first map to attach hx-vals (marshalled to JSON) to the request. Omit it (or pass nil/empty) and no hx-vals is emitted. Children passed to the component render as the initial placeholder until the swap completes.
@gothicComponents.StatefulComponentOf(&MyWidgetConfig, gothicComponents.StatefulComponentData{"id": 42}) {
<span>loading…</span>
}
The lower-level StatefulComponent(path, method, vals, hasVals) is exported too if you need to drive the wrapper without a RouteConfig.
OptimizedImage + OptimizedImageConfig — lazy image loading
OptimizedImage(props OptimizedImageProps) renders a Next.js-style lazy image: on first render it shows a blurred low-res placeholder (/public/<name>/blurred.<ext>) and an HTMX load trigger that swaps in the full-resolution image (/public/<name>/original.<ext>), which fades the placeholder out on load. OptimizedImageProps is { IsFirstLoad bool; ImgName, ImgExtension, Alt string } — set IsFirstLoad: true only when rendering the placeholder from a parent page/component.
OptimizedImageConfig is the router.RouteConfig[OptimizedImageProps] (a STATIC GET route) that serves the follow-up full-image swap; its middleware reads :name / :extension route params and the alt query param. middlewares.Middleware registers it for you at /optimizedImage/{name}/{extension}, so you normally just place OptimizedImage in a page and run gothic optimize-images to generate the blurred placeholders.
Runtime middleware — moved
The one-line runtime chi middleware (Middleware(cfg config.RuntimeConfig)) that used to live in this module now ships as its own module, github.com/gothicframework/middlewares. Import it and apply it with router.Use(middlewares.Middleware(Config.Runtime)) — see the middlewares README for details.
Requirements
- Gothic core
github.com/gothicframework/core— this module is not standalone; it renders against core'srouter.RouteConfig, is configured by core'sconfig.RuntimeConfig, and serves core'sruntimeassets. - Go 1.25+ and
go-chi/chi/v5(a transitive requirement of the runtime middleware).
Documentation
¶
Overview ¶
templ: version: v0.3.1020
templ: version: v0.3.1020
templ: version: v0.3.1020
templ: version: v0.3.1020
Index ¶
- Variables
- func OptimizedImage(componentProps OptimizedImageProps) templ.Component
- func RuntimeScripts() templ.Component
- func SigV4Enabled() bool
- func StatefulComponent(path string, method routes.HttpMethod, vals string, hasVals bool) templ.Component
- func StatefulComponentOf[T any](config *routes.RouteConfig[T], vals ...StatefulComponentData) templ.Component
- func Styles() templ.Component
- type OptimizedImageProps
- type StatefulComponentData
Constants ¶
This section is empty.
Variables ¶
var OptimizedImageConfig = routes.RouteConfig[OptimizedImageProps]{ Type: routes.STATIC, HttpMethod: routes.GET, Middleware: func(w http.ResponseWriter, r *http.Request) OptimizedImageProps { imgName := chi.URLParam(r, "name") imgExtension := chi.URLParam(r, "extension") imgAlt := r.URL.Query().Get("alt") return OptimizedImageProps{ IsFirstLoad: false, ImgName: imgName, ImgExtension: imgExtension, Alt: imgAlt, } }, }
*
- `OptimizedImageConfig` sets up a route for serving optimized images with lazy loading. *
- - `Type`: Set to `STATIC` so images are cached by CloudFront and served instantly from edge locations.
- - `HttpMethod`: Uses `GET`, which works seamlessly with HTMX for background fetching.
- - `Middleware`: Extracts route parameters (`:name`, `:extension`) and query parameters (`alt`) to
- generate the image rendering props. `IsFirstLoad` is always `false` here because only the initial
- blurred image (rendered from the parent page/component) sets it to `true`. `Priority` is always
- `false` on this HTMX follow-up path — priority images are rendered inline by the parent and never
- reach this endpoint.
Functions ¶
func OptimizedImage ¶
func OptimizedImage(componentProps OptimizedImageProps) templ.Component
func RuntimeScripts ¶
func SigV4Enabled ¶ added in v1.2.0
func SigV4Enabled() bool
SigV4Enabled reports whether the app is deployed on AWS (read once at process start, mirroring the GOTHIC_MODE pattern). When true, RuntimeScripts emits the static <meta name="gothic-provider" content="AWS"> marker that the WASM core's sigv4 extension reads at boot to enable in-path request signing (x-amz-content-sha256).
func StatefulComponent ¶
func StatefulComponentOf ¶
func StatefulComponentOf[T any]( config *routes.RouteConfig[T], vals ...StatefulComponentData, ) templ.Component
Types ¶
type OptimizedImageProps ¶
type OptimizedImageProps = struct {
IsFirstLoad bool
ImgName string
ImgExtension string
Alt string
Priority bool
}
*
- `OptimizedImageProps` defines the input props for the OptimizedImage component. *
- Fields:
- - `IsFirstLoad`: Indicates whether this is the initial blurred image request.
- - This should only be set to `true` when rendered from another component or page (like `Index`).
- - When HTMX triggers the `load` event to swap in the full image, `IsFirstLoad` is automatically `false`.
- - For a usage example, refer to the `Index` page implementation.
- - `ImgName`: The base name of the image file (e.g., "logo").
- - `ImgExtension`: The file extension (e.g., "jpeg", "png").
- - `Alt`: The image's alt text — important for accessibility and SEO.
- - `Priority`: Set `true` for an above-the-fold / LCP (Largest Contentful Paint) image.
- - The full-resolution `<img>` is then rendered DIRECTLY in the initial HTML (not
- fetched later via HTMX), so the browser's preload scanner discovers it immediately.
- - It is marked `fetchpriority="high"` and is NOT lazy-loaded, so the LCP image starts
- downloading as early as possible.
- - Leave it `false` (the default) for below-the-fold images: those keep the
- blur-up placeholder + lazy `loading="lazy"` behavior. *
- NOTE: prefer KEYED struct literals — e.g. `OptimizedImageProps{ImgName: "logo", ImgExtension: "png", Alt: "…"}`
- — so future field additions never break your call sites.
Source Files