# Gothic Framework

> Gothic is a Go SSR web framework on the GOTTH stack - Go, Templ, HTMX, Tailwind - with optional TinyGo WASM client state and one-command OpenTofu deploys to AWS.

Key facts for interpreting these docs:

- Rendering is HTMX-first server-side HTML; reach for TinyGo-compiled WASM only when you need client-side reactive state. Not a React/SPA framework.
- Routing is file-based via RouteConfig / ApiRouteConfig declarations on .templ files (STATIC, DYNAMIC, ISR).
- The `gothic` CLI (v3) drives build, wasm, css, optimize-images and deploy (OpenTofu to AWS: CloudFront + Lambda + S3).

## Getting Started

- [About](https://gothicframework.com/docs/the-tool.md): Gothic Framework builds modern Go apps with the GOTTH stack - Go, TailwindCSS, Templ, and HTMX - drawing on Next.js features for fast, scalable development.
- [Install](https://gothicframework.com/docs/install-latest.md): Install the latest gothic CLI to get started with the framework, then initialize your first project and begin building pages and components.
- [Init Command](https://gothicframework.com/docs/init-cmd.md): Run gothic init to scaffold a new Gothic project; it prompts for your Go module name and generates the starter app structure ready to run.
- [Dev Command](https://gothicframework.com/docs/dev-cmd.md): Run the Gothic dev command to serve your app locally with hot reload on route changes, giving fast feedback while you build pages and components.

## Routing & Pages

- [Routing](https://gothicframework.com/docs/file-based-routing.md): Gothic uses Next.js-style file-based routing: files in src/pages, src/components, and src/api auto-generate routes in src/routes/routes_gen.go.
- [Path Variables](https://gothicframework.com/docs/path-variables.md): Create dynamic Gothic routes with path parameters using the var_ prefix: a folder named var_userId maps to /users/:userId and is read in your middleware.
- [API Routes](https://gothicframework.com/docs/api-routes.md): Gothic API routes live in src/api and return JSON or binary responses instead of HTML - for external clients, mobile apps, and third-party integrations.
- [Static Pages](https://gothicframework.com/docs/static-pages.md): Gothic renders pages in src/pages as static by default when you export a page RouteConfig, using Cache-Control headers so a CDN like CloudFront caches them.
- [ISR Pages](https://gothicframework.com/docs/isr-pages.md): Build Gothic ISR pages with RouteConfig Type ISR and RevalidateInSec; Cache-Control headers let CloudFront cache the page and regenerate it on a schedule.
- [Dynamic Pages](https://gothicframework.com/docs/dynamic-pages.md): Create Gothic dynamic pages by setting a RouteConfig Type of DYNAMIC, so the Middleware runs on every request and passes fresh props to the page.
- [Optimized Images](https://gothicframework.com/docs/optimized-images.md): Gothic's OptimizedImage component lazy-loads images Next.js-style - a blurred low-res version shows first, then swaps to full resolution for faster perceived loads.
- [Link](https://gothicframework.com/docs/link.md): The Gothic Link component uses an official HTMX extension to preload hx-get and href URLs, emulating the Next.js Link for instant client-side navigation.
- [404 Page](https://gothicframework.com/docs/not-found-page.md): Add a custom 404 page in Gothic by creating the page and registering its route at the end of your main.go server; page functions must still receive props.

## SSR Caching

- [Cache Headers](https://gothicframework.com/docs/cache-control-headers.md): Gothic has a built-in pluggable cache for pages and API responses, configured in the Runtime block of gothic.config.go and applied by the runtime middleware.
- [In-Memory](https://gothicframework.com/docs/cache-in-memory.md): The IN_MEMORY cache strategy stores Gothic pages and API responses in a mutex-guarded Go map with TTL expiration and optional GZIP or BROTLI compression.
- [Redis](https://gothicframework.com/docs/cache-redis.md): The REDIS strategy stores Gothic cache in Redis, shared across instances and persisted through restarts, with TTL, optional TLS, and GZIP or BROTLI compression.
- [Local Files](https://gothicframework.com/docs/cache-local-files.md): The LOCAL_FILES strategy caches Gothic responses as SHA256-named files on disk - surviving restarts with no dependencies, with TTL and GZIP/BROTLI compression.

## Client-Side Go (WASM)

- [Client State](https://gothicframework.com/docs/wasm-intro.md): Gothic ClientSideState writes reactive state and DOM logic in pure Go compiled to WASM - no JavaScript bundle, no React, no Alpine - declared on any RouteConfig.
- [Observables](https://gothicframework.com/docs/wasm-observables.md): Create reactive values in Gothic WASM with CreateObservable, read them with Get, update with Set, and re-run Observe callbacks on change - like React useState.
- [DOM Helpers](https://gothicframework.com/docs/wasm-dom-helpers.md): Read and update the DOM from Go in Gothic WASM with scope-isolated helpers like SetText, SetHTML, SetValue, and AddClass after dot-importing core/wasm.
- [Event Handlers](https://gothicframework.com/docs/wasm-event-handlers.md): Wire HTML onclick, oninput, and onchange to Go in Gothic WASM by registering functions with CreateWasmFunc, CreateWasmStringFunc, and CreateWasmBoolFunc.
- [Browser APIs](https://gothicframework.com/docs/wasm-js-escape-hatch.md): Reach browser APIs without a named helper in Gothic WASM using JS(), Window(), and Document() for the global scope, plus ExecJS() to run a raw JavaScript string.
- [Storage](https://gothicframework.com/docs/wasm-storage.md): Persist Gothic WASM component state with three helpers - LocalStorage, SessionStorage, and Cookies - each offering Set, Get, and Remove for the lifetime you need.
- [HTTP & Files](https://gothicframework.com/docs/wasm-http-and-files.md): Fetch in Gothic WASM returns a Response with Status, Headers, and Body: use .Text(), .Bytes(), and .OK(), send FetchConfig bodies, and read or push files with GetFileBytes and TriggerDownload.
- [Async Fetch](https://gothicframework.com/docs/wasm-fetch-async.md): Fetch from Go WASM three ways in Gothic: blocking Fetch, FetchAsync callbacks, and FetchChan channels for concurrent fan-out, with automatic per-component request cancellation.
- [Typed JSON](https://gothicframework.com/docs/wasm-typed-json.md): Decode[T] turns a Gothic WASM Response into a typed Go struct with no reflection, matched by json tags; MapAny reads it untyped. Keep shared DTOs in a net/http-free package.
- [Encode JSON](https://gothicframework.com/docs/wasm-encode-json.md): Encode[T] marshals a typed Go struct into JSON request-body bytes in Gothic WASM: reflection-free and symmetric to Decode, for a drift-free own-BFF round trip.
- [HTMX](https://gothicframework.com/docs/wasm-htmx.md): The Gothic WASM HTMX struct mirrors htmx 2.0.3 from Go: Ajax and Swap render trusted HTML and boot nested components, plus Process and Trigger with typed HtmxEvent consts.
- [HTMX DOM](https://gothicframework.com/docs/wasm-htmx-dom.md): Listen and mutate the DOM from Go with Gothic's HTMX struct: scoped leak-safe On, OnGlobal, and Off, class helpers, Find, FindAll, Closest, Values, and Remove.
- [Topics](https://gothicframework.com/docs/wasm-topics.md): Gothic Topics let multiple WASM components on a page share reactive state - like React useContext - via a struct in src/topics with ObservableField fields.
- [External Imports](https://gothicframework.com/docs/wasm-external-imports.md): Gothic v3 ClientSideState can import any local package - shared utils, a codec, even a server-rendered templ component - for isomorphic Go across server and WASM.
- [Compiler Options](https://gothicframework.com/docs/wasm-compiler-options.md): Every Gothic ClientSideState page compiles to WASM; pick one of three compilers and two compression formats per route on the page's RouteConfig.

## Infrastructure

- [AWS Cloud](https://gothicframework.com/docs/aws-cloud.md): Gothic ships a default serverless infrastructure - a CDN, server, object storage, and deployment tool - provisioned on AWS from a single gothic deploy command.
- [CloudFront CDN](https://gothicframework.com/docs/cloud-cdn.md): Gothic serves static assets and optimized images through AWS CloudFront, caching public folder files at S3-backed edge locations for fast global delivery.
- [App Server](https://gothicframework.com/docs/cloud-server.md): Gothic runs your Go app as an AWS Lambda container image stored in ECR, fronted by a Lambda Function URL for automatic, fully managed scaling.
- [Deployment Tool](https://gothicframework.com/docs/deployment-tool.md): Gothic uses OpenTofu to define and deploy serverless infrastructure declaratively - consistent, repeatable, cloud-agnostic deploys with minimal manual config.

## Deploy

- [Dependencies](https://gothicframework.com/docs/deploy-install-dependencies.md): Before deploying a Gothic app to AWS, create an AWS account and install the AWS CLI and Docker so the gothic CLI can provision your infrastructure.
- [Deploy Config](https://gothicframework.com/docs/deploy-configuration.md): Configure Gothic deployments by declaring a Deploy block in gothic.config.go - a real Go file the CLI parses statically, reading your module path from go.mod.
- [Deploy Commands](https://gothicframework.com/docs/deploy-cmds.md): Run gothic deploy --action deploy --stage to provision a Gothic app's CloudFront CDN, Lambda container server, and S3 image bucket in one command.
- [Lifecycle Hooks](https://gothicframework.com/docs/lifecycle-hooks.md): Run custom Go around a Gothic deploy with the optional BeforeDeploy and AfterDeploy hooks in gothic.config.go - seed a database, warm a cache, or notify Slack.
- [Custom Infra](https://gothicframework.com/docs/custom-infra.md): Extend Gothic's OpenTofu stack with your own AWS resources by dropping .tf or .tf.json files into an infra/ folder - merged into the same module and state.
- [Custom Dockerfile](https://gothicframework.com/docs/custom-dockerfile.md): Point Gothic at your own Dockerfile with the DockerfilePath field in gothic.config.go, resolved relative to project root and applied on the next gothic deploy.
- [Migrate v3](https://gothicframework.com/docs/migrate-v3.md): Move a v2 Gothic project to v3 with the built-in migrator, converting old felipegenef imports and SAM deploys to the gothicframework org modules and OpenTofu.

## Optional

- [HTMX reference](https://htmx.org/reference/): Upstream HTMX attribute and header reference
- [Templ documentation](https://templ.guide/): Upstream Templ templating language docs
- [Source on GitHub](https://github.com/gothicframework): Gothic Framework modules and the gothic CLI