gowdk

README

GoWDK

GoWDK compiles .gwdk pages ahead of time into plain, inspectable Go — net/http routes, form decoders, guards — and packages the whole app into one binary. Build-time rendering is the default; request-time SSR is opt-in per page. No reflection, no request-time magic.

Status: experimental 0.x pre-release. Public contracts can still change. Not production-ready.

Website warning: the public project page is not updated yet and is currently only a placeholder. Treat this README and the docs in this repository as the current source of truth.

Install

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

Or use the install script:

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

Pin the current CLI release:

GOWDK_VERSION=v0.2.8 GOWDK_INSTALL_DIR="$HOME/.local/bin" \
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/cssbruno/GoWDK/main/scripts/install.sh)"

Build from source:

git clone https://github.com/cssbruno/GoWDK.git
cd GoWDK
go build ./cmd/gowdk
./gowdk version

Quickstart: Single-Page Server

Create a one-page app, build its generated server, and run the binary:

gowdk init --tests --template site ./hello-gowdk
cd ./hello-gowdk
gowdk build
./bin/site

Open http://127.0.0.1:8080/. A minimal page:

package pages

use widgets "components"

@route "/"
@guard public

build {
  => { title: "GoWDK ships apps" }
}

view {
  <main>
    <h1>{title}</h1>
    <p>A .gwdk page compiled into an embedded Go server.</p>
    <widgets.Counter />
  </main>
}

Add local reactivity:

// ui/counter.go
package ui

type CounterState struct {
	Count int `json:"count"`
}

func NewCounterState() CounterState {
	return CounterState{Count: 0}
}

// components/counter.cmp.gwdk
package components

import ui "github.com/acme/hello-gowdk/ui"

@component Counter

state ui.CounterState = ui.NewCounterState()

client {
  computed Label string {
    if Count == 0 {
      return "Start"
    }
    return string(Count)
  }

  func Increment() {
    Count++
  }

  func Reset() {
    Count = 0
  }
}

view {
  <section>
    <p class:active={Count > 0}>{Label}</p>
    <button g:on:click={Increment()}>Add</button>
    <button g:if={Count > 0} g:on:click={Reset()}>Reset</button>
  </section>
}

Replace github.com/acme/hello-gowdk/ui with your app module path.

Design

How responsibility is split, and the opinions behind it:

• .gwdk files declare pages, components, layouts, routes, views, build data, browser behavior hooks, and endpoint metadata.
• Normal Go packages own handlers, domain logic, auth, persistence, contracts, jobs, integration events, and production validation.
• The compiler parses .gwdk, validates contracts, lowers to inspectable IR, and emits HTML, assets, manifests, build reports, and generated Go adapters.
• Generated Go is runtime wiring: net/http routes, form decoders, response envelopes, CSRF checks, fragments, SSR/load calls, guards, rate limits, and contract web adapters.
• Build-time SPA/static output is the default page lane. load {} and go ssr {} opt pages into request-time rendering. Actions, APIs, and fragments are request-time endpoints without forcing full-page SSR.
• Generated browser code is compiler-owned enhancement for SPA navigation, partial form posts, fragments, local islands, and WASM mounts. User JS, TypeScript, npm assets, and framework interop stay explicit and page-scoped.
• Runtime core stays dependency-light. Framework adapters, Tailwind, Redis, NATS, WebSocket fanout, and similar integrations live in optional addons or nested modules.
• Unsupported source should fail with diagnostics before generated output gets clever or surprising.

What Works Today

This table describes the current demoable 0.x slice. "Partial" means the listed path works, but the public contract is not stable and the remaining limit is still tracked in the hardening backlog.

Surface	Status	Works Today	Current Limit	Docs	Example
Static build output	Implemented	gowdk build --out emits HTML, route metadata, and asset metadata for simple build-time pages.	Generated output is still pre-1.0.	CLI	Pages
Dynamic SPA paths	Partial	Dynamic SPA routes can be expanded from the first supported literal paths {} subset.	Dynamic SPA routes need paths {} unless the page uses request-time rendering.	Routing	Blog
Build-time Go data	Partial	Literal build records and supported no-argument Go build functions can feed SPA rendering.	Arbitrary build-time Go statements and broader data lifecycles are not stable.	Data	Go interop
Actions	Partial	Generated apps can serve typed POST action handlers, decode supported form inputs, validate request shape, return redirects/fragments, and opt into CSRF.	File uploads, multipart generated forms, and domain validation stay in user-owned Go handlers.	Actions	Login
APIs	Partial	Feature-bound API handlers can be generated for supported signatures.	Typed body/query helpers and broader error/status contracts remain planned.	API	API
Fragments	Partial	Partial form submissions and standalone fragment routes can return server fragments and remount local islands.	Richer fragment rendering and broader local client behavior are still hardening work.	Partials	Fragments
SSR	Partial	Pages with load {} or go ssr {} can build request-time handlers when the SSR addon is enabled.	Typed route-param accessors, lifecycle docs, and error/cache contracts need more hardening.	SSR	SSR
Hybrid	Partial	Hybrid request-time route metadata and generated request-time pages exist for the supported slice.	The public hybrid source contract, streaming, and data refresh policy are not stable.	Hybrid	Hybrid
Components	Partial	Components support imported contracts, slots, scoped CSS/assets, first local client behavior, and generated island assets.	Non-string props, richer slots/events, real g:if/g:for, lifecycle cleanup, and dependency diagnostics are planned.	Components	Components
WASM islands	Partial	Component-level @wasm and page-level go client {} can emit Go js/wasm browser assets for supported fixtures.	ABI docs, size reporting, runtime validation, and browser behavior coverage need hardening.	Components	Test fixture
CSS/assets	Partial	CSS processors, page CSS, scoped component CSS, component assets, asset manifests, content-hashed filenames, and optional Tailwind wrapper exist.	CSS processor contracts and optional dependency boundaries need hardening.	CSS	CSS
One-binary output	Partial	gowdk build --app --bin can generate and compile an embedded Go server for supported SPA/backend/SSR slices.	Runtime operations, split/backend-only deploys, and artifact smoke coverage are still expanding.	Deployment	Embed
Contracts	Partial	Runtime contracts support typed queries, commands, events, jobs, role filtering, local dispatch, file outbox, broker/fanout adapters, contract graph/trace/list commands, and generated g:command/g:query web adapters.	Split worker/cron generation, retry policy, managed deployment recipes, and editor-first contract visualization remain planned.	Contracts	Runtime contracts
Dev server	Partial	gowdk dev polls inputs, skips no-op rebuilds, serves or runs generated output, live-reloads browsers, shows a browser overlay for rebuild failures, and keeps serving the last successful output.	Overlay diagnostics need codes, source spans, changed-file context, and better generated-app runtime attribution. Component HMR is intentionally deferred.	Dev	Getting started
Editor/LSP	Implemented	The VS Code extension and dependency-free LSP provide diagnostics, formatting, completions, hover, outline, semantic tokens, definitions, references, site-map visualization, and project-aware navigation for supported paths.	Exact source ranges, richer quick fixes, route/endpoint/contract maps, and g:command/g:query status in the editor are planned.	Language server	VS Code

Security note: request-time features are still 0.x, but the core request-time hardening is now in place. Generated handlers apply body-size limits (actions and APIs), server read/header/write/idle timeouts, and a per-request handler deadline; recovered panics return a generic no-store 500 and are logged server-side with secret redaction; CSRF is opt-in with a 403 invalid-token contract; redirects are validated against a safe allowlist (local paths only, no protocol-relative or CRLF, same-origin referer); and diagnostics redact secrets quoted from source. Still hardening: full auth/session, multipart uploads, and the broader operations policy.

Known gaps and release hardening work live in the 0.x improvement checklist, with public tracking in the 0.x Hardening project.

Development

Run the full Go test gate, including nested optional adapter modules:

scripts/test-go-modules.sh

Run the root module only:

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

Run the all-module vulnerability gate before release-style dependency changes:

scripts/vulncheck-go-modules.sh

Docs

• Getting started
• Changelog
• 0.x improvement checklist
• v0.2 release checklist
• Public 0.x hardening backlog
• Examples

Documentation

Index

• Constants
• type Addon
  • func NewAddon(name string, features ...Feature) Addon
• type AssetMode
• type BuildConfig
  • func (config BuildConfig) DebugAssets() bool
• type BuildMode
• type BuildTargetConfig
• type CSRFConfig
  • func (config CSRFConfig) SecretEnvName() string
• type CSSAsset
• type CSSConfig
• type CSSContext
• type CSSOutputConfig
• type CSSProcessor
• type CSSResult
• type CSSSource
• type Config
  • func (config Config) HasFeature(feature Feature) bool
• type EnvConfig
  • func (config EnvConfig) Validate(lookup func(string) (string, bool)) error
• type EnvValidationError
  • func (err EnvValidationError) Error() string
• type EnvValidationErrors
  • func (errs EnvValidationErrors) Error() string
• type EnvVar
• type Feature
• type FeatureSet
  • func EnabledFeatures(config Config) FeatureSet
  • func (features FeatureSet) Has(feature Feature) bool
• type GoBlockConsumer
• type GoBlockContext
• type GoBlockDiagnostic
• type GoBlockFile
• type GoBlockTarget
• type HeadConfig
• type ModuleConfig
• type RenderConfig
  • func (config RenderConfig) DefaultMode() RenderMode
• type RenderMode
  • func ParseRenderMode(value string) (RenderMode, error)
  • func (mode RenderMode) IsBuildTime() bool
  • func (mode RenderMode) RequiresSSR() bool
• type Script
• type SecretEnv
• type SourceConfig
• type SourcePosition
• type SourceSpan
• type Stylesheet

Constants

const DefaultCSRFSecretEnv = "GOWDK_CSRF_SECRET"

Types

type Addon

type Addon interface {
	Name() string
	Features() []Feature
}

Addon is the minimal contract every optional GOWDK capability implements.

func NewAddon

func NewAddon(name string, features ...Feature) Addon

NewAddon creates a simple addon declaration for capability registration.

type AssetMode

type AssetMode string

AssetMode controls how frontend artifacts are shipped.

const (
	AssetExternal AssetMode = "external"
	Embed         AssetMode = "embed"
)

type BuildConfig

type BuildConfig struct {
	Output              string
	Mode                BuildMode
	Assets              AssetMode
	Head                HeadConfig
	CSRF                CSRFConfig
	AllowMissingBackend bool
	Stylesheets         []Stylesheet
	Scripts             []Script
	Targets             []BuildTargetConfig
}

BuildConfig controls output artifacts and frontend asset packaging.

func (BuildConfig) DebugAssets

func (config BuildConfig) DebugAssets() bool

DebugAssets reports whether generated frontend artifacts should include debugging metadata.

type BuildMode

type BuildMode string

BuildMode controls whether generated frontend artifacts include development metadata such as source maps. Development is the default when omitted.

const (
	Development BuildMode = "development"
	Production  BuildMode = "production"
)

type BuildTargetConfig

type BuildTargetConfig struct {
	Name          string
	Modules       []string
	Output        string
	App           string
	Binary        string
	WASM          string
	BackendApp    string
	BackendBinary string
}

BuildTargetConfig declares one configured build target. Modules selects the configured source modules compiled into Output, App, Binary, WASM, BackendApp, and BackendBinary.

type CSRFConfig

type CSRFConfig struct {
	Enabled    bool
	SecretEnv  string
	CookieName string
	FieldName  string
	HeaderName string
	Insecure   bool
}

CSRFConfig controls generated action CSRF token wiring.

func (CSRFConfig) SecretEnvName

func (config CSRFConfig) SecretEnvName() string

SecretEnvName returns the environment variable used by generated apps to read the CSRF signing secret.

type CSSAsset

type CSSAsset struct {
	Path     string
	Contents []byte
}

CSSAsset is a CSS file emitted by a compile-time CSS processor.

type CSSConfig

type CSSConfig struct {
	Include []string
	Exclude []string
	Default []string
	Output  CSSOutputConfig
}

CSSConfig controls discovered CSS inputs and page CSS output.

type CSSContext

type CSSContext struct {
	Sources   []CSSSource
	OutputDir string
	Build     BuildConfig
	CSS       CSSConfig
}

CSSContext is passed to compile-time CSS processors.

type CSSOutputConfig

type CSSOutputConfig struct {
	Dir        string
	HrefPrefix string
}

CSSOutputConfig controls generated page stylesheet locations.

type CSSProcessor

type CSSProcessor interface {
	Addon
	ProcessCSS(CSSContext) (CSSResult, error)
}

CSSProcessor is implemented by addons that emit CSS at build time.

type CSSResult

type CSSResult struct {
	Assets          []CSSAsset
	Stylesheets     []Stylesheet
	PageStylesheets map[string][]Stylesheet
}

CSSResult is returned by compile-time CSS processors.

type CSSSource

type CSSSource struct {
	Path       string
	Kind       string
	Name       string
	CSSClasses []string
}

CSSSource describes one discovered source file for compile-time CSS plugins.

type Config

type Config struct {
	AppName string
	Source  SourceConfig
	Modules []ModuleConfig
	Render  RenderConfig
	Env     EnvConfig
	Build   BuildConfig
	CSS     CSSConfig
	Addons  []Addon
}

Config describes how a GOWDK application should be discovered, compiled, and packaged.

func (Config) HasFeature

func (config Config) HasFeature(feature Feature) bool

HasFeature reports whether a config enables a feature through an addon.

type EnvConfig

type EnvConfig struct {
	Vars    []EnvVar
	Secrets []SecretEnv
}

EnvConfig declares the runtime environment contract for generated apps. It names expected variables and secrets, but never stores secret values.

func (EnvConfig) Validate

func (config EnvConfig) Validate(lookup func(string) (string, bool)) error

Validate checks the env contract. If lookup is nil, only structural rules are checked. If lookup is provided, required missing names are reported too.

type EnvValidationError

type EnvValidationError struct {
	Code    string
	Name    string
	Message string
}

EnvValidationError describes one invalid or missing env contract entry.

func (EnvValidationError) Error

func (err EnvValidationError) Error() string

type EnvValidationErrors

type EnvValidationErrors []EnvValidationError

EnvValidationErrors is a list of env contract validation failures.

func (EnvValidationErrors) Error

func (errs EnvValidationErrors) Error() string

type EnvVar

type EnvVar struct {
	Name     string
	Required bool
	Default  string
}

EnvVar declares a normal non-secret environment variable. Defaults must only be used for safe non-secret local or runtime values.

type Feature

type Feature string

Feature names the capabilities that addons make available to the compiler.

const (
	FeatureSPA       Feature = "spa"
	FeatureActions   Feature = "actions"
	FeaturePartial   Feature = "partial"
	FeatureSSR       Feature = "ssr"
	FeatureAPI       Feature = "api"
	FeatureEmbed     Feature = "embed"
	FeatureCSS       Feature = "css"
	FeatureRateLimit Feature = "ratelimit"
	FeatureContracts Feature = "contracts"
	FeatureAuth      Feature = "auth"
	FeatureDB        Feature = "db"
)

type FeatureSet

type FeatureSet map[Feature]bool

FeatureSet is a lookup table of enabled addon capabilities.

func EnabledFeatures

func EnabledFeatures(config Config) FeatureSet

EnabledFeatures returns the set of capabilities enabled by a config.

func (FeatureSet) Has

func (features FeatureSet) Has(feature Feature) bool

Has reports whether a feature is present in the set.

type GoBlockConsumer

type GoBlockConsumer interface {
	GoBlockTargets() []string
	ValidateGoBlock(target GoBlockTarget, context GoBlockContext) []GoBlockDiagnostic
	GeneratedGo(target GoBlockTarget, context GoBlockContext) ([]GoBlockFile, error)
}

GoBlockConsumer is an optional addon extension point for targeted go blocks such as go addon.contracts {}.

type GoBlockContext

type GoBlockContext struct {
	Render RenderMode
}

GoBlockContext describes the compiler lane that owns a go block target.

type GoBlockDiagnostic

type GoBlockDiagnostic struct {
	Code    string
	Message string
	Span    SourceSpan
}

GoBlockDiagnostic is an addon-produced diagnostic for a go block target.

type GoBlockFile

type GoBlockFile struct {
	Path    string
	Source  string
	Package string
}

GoBlockFile is a generated file emitted by an addon go block consumer. Path is relative to the generated app directory.

type GoBlockTarget

type GoBlockTarget struct {
	Target       string
	OwnerKind    string
	OwnerID      string
	OwnerPackage string
	SourcePath   string
	Body         string
	Span         SourceSpan
}

GoBlockTarget describes one parsed go block passed to an addon.

type HeadConfig

type HeadConfig struct {
	SiteName    string
	Favicon     string
	Image       string
	TwitterCard string
}

HeadConfig controls app-level document head tags emitted around page metadata.

type ModuleConfig

type ModuleConfig struct {
	Name   string
	Type   string
	Source SourceConfig
}

ModuleConfig names a source group inside a GOWDK app. Build discovery uses selected module sources to decide what gets compiled into output, generated apps, and generated binaries. Type is user-defined metadata.

type RenderConfig

type RenderConfig struct {
	Default RenderMode
}

RenderConfig controls default render behavior. SPA is the default when omitted.

func (RenderConfig) DefaultMode

func (config RenderConfig) DefaultMode() RenderMode

DefaultMode returns SPA when no explicit default render mode is set.

type RenderMode

type RenderMode string

RenderMode describes where full-page HTML is produced.

const (
	// SPA emits a non-SSR app shell and client-side route experience.
	SPA RenderMode = "spa"
	// Action emits a non-SSR app shell while allowing backend actions.
	Action RenderMode = "action"
	// Hybrid allows a route to combine app output and request-time behavior.
	Hybrid RenderMode = "hybrid"
	// SSR renders full pages at request time through the SSR addon.
	SSR RenderMode = "ssr"
)

func ParseRenderMode

func ParseRenderMode(value string) (RenderMode, error)

ParseRenderMode validates a render mode from source.

func (RenderMode) IsBuildTime

func (mode RenderMode) IsBuildTime() bool

IsBuildTime reports whether this mode is always build-time. Hybrid defaults to build-time unless explicit request-time capabilities are declared.

func (RenderMode) RequiresSSR

func (mode RenderMode) RequiresSSR() bool

RequiresSSR reports whether this mode always needs the SSR addon. Hybrid pages need SSR only when they declare explicit request-time capabilities.

type Script

type Script struct {
	Src  string
	Type string
}

Script describes one script tag emitted into generated HTML. Type is optional; use "module" for ES module bundles.

type SecretEnv

type SecretEnv struct {
	Name     string
	Required bool
}

SecretEnv declares a secret environment variable. Secret values intentionally have no config field and must come from the runtime environment.

type SourceConfig

type SourceConfig struct {
	Include []string
	Exclude []string
}

SourceConfig selects portable .gwdk files for discovery.

type SourcePosition

type SourcePosition struct {
	Line   int
	Column int
}

SourcePosition is a 1-based source location exposed to addon go block consumers.

type SourceSpan

type SourceSpan struct {
	Start SourcePosition
	End   SourcePosition
}

SourceSpan is a 1-based source range exposed to addon go block consumers.

type Stylesheet

type Stylesheet struct {
	Href string
}

Stylesheet describes one stylesheet link emitted into generated HTML.