GOWDK

A compile-first web kit for full-stack Go applications.

Write portable .gwdk pages and components, keep application logic in normal Go, and compile the result into static output, generated Go source, or a single deployable binary—without maintaining a separate JavaScript application stack.

Warning

GOWDK is experimental pre-1.0 compiler/runtime software. The language, generated output, runtime contracts, and CLI may change. Generated applications are not production-ready security enforcement; review SECURITY.md before evaluating a deployment.

What GOWDK does

GOWDK gives a Go project a declarative UI layer while leaving data access, business rules, integrations, and operational code in ordinary Go packages.

• .gwdk files declare pages, components, layouts, routes, forms, APIs, fragments, rendering behavior, and bounded client interactions.
• The compiler discovers, parses, type-checks, and validates those declarations before generating browser assets and normal Go source.
• Applications can emit build-time static/SPA output, opt into hybrid or SSR routes, and package supported request-time behavior into a Go binary.
• Generated code and build metadata remain inspectable. Core builds use the Go toolchain; Tailwind and other external tools are explicit, optional choices.
• Browser runtime code is generated by GOWDK. Go/WASM islands are explicit rather than the default component model.

Quick start

GOWDK currently requires Go 1.26.4.

Install through the Go module checksum system:

go install github.com/cssbruno/gowdk/cmd/gowdk@latest
gowdk version

For reproducible installs, replace latest with an exact published tag. A convenience installer is also available for supported Linux and macOS targets:

curl -fsSL https://raw.githubusercontent.com/cssbruno/GoWDK/main/scripts/install.sh | sh

The installer verifies the downloaded release binary against checksums.txt; the bootstrap script itself is fetched from the mutable main branch. See Getting Started for exact artifact and attestation verification.

Create, verify, build, and run an application:

gowdk init --tests --template site my-app
cd my-app

gowdk check
gowdk build
gowdk test
./bin/site

Open http://127.0.0.1:8080/. During development, use:

gowdk dev

The dev loop rebuilds changed inputs, serves the last successful build after an error, and supports browser live reload.

A .gwdk page

package app

route "/"
guard public
css default page

build {
  => { title: "Hello from GOWDK" }
}

view {
  <main class="home">
    <h1>{title}</h1>
    <p>Compiled from a .gwdk page and served by Go.</p>
  </main>
}

Pages can call declared components, bind build-time data returned by Go, declare form actions and API routes, render fragments, or opt into request-time loading. Domain behavior stays in exported Go functions with compiler-validated signatures.

Compilation model

.gwdk sources + gowdk.config.go + normal Go packages
                         |
                 discover / parse
                         |
                typed AST and IR
                         |
              validate all contracts
                         |
          +--------------+---------------+
          |              |               |
    static/SPA      generated Go      reports and
      output            app           manifests
                             |
                          go build
                             |
                   deployable Go binary

GOWDK supports three page rendering lanes:

Lane	Behavior
Static/SPA	Produces build-time HTML/app output and supported client navigation.
Hybrid	Stays build-time by default and adds request-time behavior only when declared.
SSR	Produces full page HTML at request time through the SSR addon.

Capabilities

Area	Current surface
UI	Pages, components, layouts, slots, scoped assets, CSS, literal dynamic paths, and build-time data.
Backend	Form actions, typed inputs, redirects, fragments, APIs, guards, request-time page loaders, and panic boundaries.
Go interoperability	Imported build functions, normal handler packages, database/sql or any Go data layer, lifecycle services, and generated adapter validation.
Packaging	Static output, generated app source, embedded assets, local binaries, optional Docker files, deploy recipe starters, and Go js/wasm artifacts.
Extensions	Built-in feature addons for SSR, actions, APIs, partials, CSS/Tailwind, SEO, auth, DB plumbing, contracts, realtime, rate limiting, and observability.
Tooling	Scaffolding, formatting, diagnostics, safe fixes, tests, security audits, route and graph inspection, development serving, preview, LSP, and a VS Code extension.

The broad surface is intentional, but maturity is not uniform. Richer client-side reactivity, hybrid streaming, browser-owned server-data refresh, non-HTTP revalidation, scheduler policy, authentication hardening, and parts of the production security model remain partial or application-owned.

Generated project layout

The default site scaffold starts with:

my-app/
├── gowdk.config.go
├── src/
│   ├── pages/home.page.gwdk
│   └── components/hero.cmp.gwdk
├── styles/global.css
├── tests/gowdk_smoke_test.go
└── go.mod

A configured build target then produces:

.gowdk/output/site/   # HTML, assets, route metadata, and build report
.gowdk/site/          # generated, inspectable Go application
bin/site              # deployable binary with embedded output

Generated directories should not be edited by hand.

Everyday CLI

Command	Purpose
gowdk init	Scaffold a site or minimal application.
gowdk dev	Rebuild, serve, restart generated apps when needed, and live reload.
gowdk build	Compile selected sources and configured targets.
gowdk preview	Build and serve a one-shot deployment preview.
gowdk check	Parse and validate .gwdk sources.
gowdk fmt --write	Format .gwdk files.
gowdk test	Run Go tests against generated application artifacts.
gowdk doctor	Check the local toolchain and project health.
gowdk audit	Evaluate the generated application's declared security posture.
gowdk inspect	Inspect compiler IR, trees, endpoint graphs, assets, and Go bindings.
gowdk routes / endpoints	Print generated route and endpoint metadata.
gowdk lsp	Start the language server over stdio.

Run gowdk --help or gowdk <command> --help for the complete command surface.

Addons

Capabilities are enabled explicitly in gowdk.config.go with addon constructors such as ssr.Addon() or api.Addon(). For most built-ins this is a feature declaration that selects GOWDK-owned compiler and generator behavior; request-time helpers live under runtime/, and application services are wired from normal Go. The CLI can list and wire supported built-in addons:

gowdk add --list
gowdk add --list --registry
gowdk add ssr actions api
gowdk add seo --base-url https://example.com

GOWDK does not silently download external tools, scan GitHub for addons, or execute unknown addon code. External modules and tools remain normal, application-owned dependencies. See the addons reference.

Deployment

A generated binary serves embedded frontend output plus the supported actions, APIs, fragments, guards, hybrid routes, and SSR routes compiled into it. Generated binaries speak HTTP; TLS and public routing normally belong to a reverse proxy such as Caddy or Nginx.

gowdk build can also emit Docker support and starter deployment recipes:

gowdk build --docker
gowdk build --deploy-recipe caddy

Available recipe families include caddy, nginx, split, static, and systemd. See Deployment for output models, reverse proxies, environment contracts, and operational guidance.

Documentation

Start with the Documentation Hub, which maps each question to its authoritative source and explains how current contracts, specifications, plans, ADRs, and release history differ.

Need	Start here
First application	Getting Started, Native Learning Path, and Cookbook
.gwdk language	Language Index
Commands, config, runtime, and integrations	Reference Index
Compiler pipeline and generated output	Compiler Index
Capability status and product direction	Product Index
Architecture, security, operations, and contribution standards	Engineering Index
Security and release history	Security Policy and Changelog

Runnable projects live under examples/. The examples/flagship/ project crosses most supported application surfaces in one generated application.

Contributing

GOWDK is early-stage compiler infrastructure. Keep changes focused, update the relevant contract documentation, and run at least:

go test ./...
go build ./cmd/gowdk

See Contributing for repository workflow, documentation ownership, and verification expectations.

License

GOWDK is licensed under the Mozilla Public License 2.0.