gowdk

README

GOWDK

GOWDK is a portable Go web compiler. Write movable .gwdk files, compile first, and ship static output or a single Go binary. SSR is available. Live demo: gowdk.com Demo source: cssbruno/gowdk-page

Install Loop

During source development, run the CLI from this repository:

go run ./cmd/gowdk <command>

Create and serve an app:

go run ./cmd/gowdk init my-app
cd my-app
go run ../cmd/gowdk build
go run ../cmd/gowdk serve --dir dist/site

Build an example:

go run ./cmd/gowdk build --out /tmp/gowdk-build \
  examples/basic/home.page.gwdk \
  examples/basic/hero.cmp.gwdk

go run ./cmd/gowdk serve --dir /tmp/gowdk-build

Use dev for rebuild, serve, watch, and browser reload:

go run ./cmd/gowdk dev --out /tmp/gowdk-build examples/basic/*.gwdk

Site Example

@page blog.post
@route "/blog/{slug}"
@layout root, blog
@render static

paths {
  => { slug: "hello-gowdk" }
  => { slug: "compile-first" }
}

build {
  => {
    title: "GOWDK ships apps",
    description: "Portable pages, build-time data, actions, and fragments."
  }
}

act refresh {
  input := form ArticleFilter
  fragment "#article-list" {
    <section>
      <h2>Updated articles</h2>
      <p>Server-rendered fragment returned by an action.</p>
    </section>
  }
  -> "/blog/{slug}"
}

view {
  <main class="page">
    <header class="hero">
      <p>Compile-first Go UI</p>
      <h1>{title}</h1>
      <p data-slug="{slug}">{description}</p>
    </header>

    <form g:post={refresh} g:target="#article-list" g:swap="innerHTML">
      <input name="query" placeholder="Filter articles" />
      <button>Refresh</button>
    </form>

    <section id="article-list">
      <article>
        <h2>{slug}</h2>
        <p>Generated as static HTML at build time.</p>
      </article>
    </section>
  </main>
}

CLI

gowdk init [--force] [dir]
gowdk check [--config <file>] [--module <name>] [--json] [--ssr] [files...]
gowdk build [--config <file>] [--debug] [--ssr] [--target <name>] [--module <name>] [--out <dir>] [--app <dir>] [--bin <file>] [--wasm <file>] [files...]
gowdk dev [--addr 127.0.0.1:8080] [--interval 1s] [build flags...]
gowdk watch [--once] [--restart] [--interval 1s] [build flags...]
gowdk serve --dir <dir> [--addr 127.0.0.1:8080]
gowdk fmt [--write] <file.gwdk>
gowdk tokens <file.gwdk>
gowdk manifest [--config <file>] [--module <name>] [--ssr] [files...]
gowdk sitemap [--config <file>] [--module <name>] [--ssr] [files...]
gowdk routes [--config <file>] [--module <name>] [--ssr] [files...]
gowdk lsp [--ssr]

Every successful disk build writes gowdk-build-report.json. Pass --debug to mirror the structured report to stderr.

Build Targets

gowdk.config.go can declare named outputs:

Build: gowdk.BuildConfig{
	Targets: []gowdk.BuildTargetConfig{
		{Name: "admin", Modules: []string{"admin"}, Output: "dist/admin", App: ".gowdk/admin", Binary: "bin/admin"},
		{Name: "site", Modules: []string{"public"}, Output: "dist/site", App: ".gowdk/site", Binary: "bin/site"},
	},
}

Run all targets:

gowdk build

Run one target:

gowdk build --target admin

Quality Gates

gofmt -w <changed-go-files>
go test ./...
go build ./cmd/gowdk
node --check editors/vscode/extension.js
node --check editors/vscode/extension-core.js
node --test editors/vscode/*.test.js
go run ./cmd/gowdk check --ssr examples/basic/*.gwdk

CI also smoke-builds static, dynamic, CSS, and embedded-binary examples.

Docs

• Product vision
• Requirements
• Roadmap
• Architecture
• CLI reference
• Language notes
• Examples
• VS Code extension

Documentation

Index

• type Addon
  • func NewAddon(name string, features ...Feature) Addon
• type AssetMode
• type BuildConfig
  • func (config BuildConfig) DebugAssets() bool
• type BuildMode
• type BuildTargetConfig
• type CSSAsset
• type CSSConfig
• type CSSContext
• type CSSOutputConfig
• type CSSProcessor
• type CSSResult
• type CSSSource
• type Config
  • func (config Config) HasFeature(feature Feature) bool
• type Feature
• type FeatureSet
  • func EnabledFeatures(config Config) FeatureSet
  • func (features FeatureSet) Has(feature Feature) bool
• 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 SourceConfig
• type Stylesheet

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
	Stylesheets []Stylesheet
	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
}

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

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
}

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
	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 Feature

type Feature string

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

const (
	FeatureStatic    Feature = "static"
	FeatureActions   Feature = "actions"
	FeaturePartial   Feature = "partial"
	FeatureSSR       Feature = "ssr"
	FeatureAPI       Feature = "api"
	FeatureEmbed     Feature = "embed"
	FeatureCSS       Feature = "css"
	FeatureRateLimit Feature = "ratelimit"
)

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 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. Static is the default when omitted.

func (RenderConfig) DefaultMode

func (config RenderConfig) DefaultMode() RenderMode

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

type RenderMode

type RenderMode string

RenderMode describes where full-page HTML is produced.

const (
	// Static renders full pages at build time.
	Static RenderMode = "static"
	// Action renders the page statically while allowing backend actions.
	Action RenderMode = "action"
	// Hybrid allows a route to combine static 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 route params must be known at build time.

func (RenderMode) RequiresSSR

func (mode RenderMode) RequiresSSR() bool

RequiresSSR reports whether this mode needs the SSR addon.

type SourceConfig

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

SourceConfig selects portable .gwdk files for discovery.

type Stylesheet

type Stylesheet struct {
	Href string
}

Stylesheet describes one stylesheet link emitted into generated HTML.