Documentation
¶
Overview ¶
Package static implements static-site generation for a framework.App with a UIHost mounted on it. The Builder walks every registered route, runs the screen's Load(ctx) hook, renders to HTML, and writes the result to disk along with the runtime.js, compiled actions, and any static assets.
Dynamic routes (paths containing ":param" segments) participate when the screen's component implements core-ui/app.StaticPathsProvider; the builder expands the pattern against each returned param map.
Build output is suitable for any static host (S3, GitHub Pages, Cloudflare Pages, etc.). The runtime.js included alongside the HTML drives client-side navigation, form actions, and signal-driven updates after first paint, so behavior matches the SSR server.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// Host is the UIHost to render through. Must already have its screens,
// actions, and static assets configured.
Host *uihost.UIHost
// OutDir is the destination directory; existing contents are overwritten.
OutDir string
// BasePath is the URL subpath the static site is served under (e.g.
// "/gofastr" for a GitHub Pages project site at
// https://user.github.io/gofastr/). Empty = apex (root-absolute
// URLs, the default). When set, the builder rewrites every
// root-absolute /__gofastr/... asset URL and internal nav link in
// the emitted HTML, and bakes the prefix into runtime.js's
// dynamically-constructed module URLs, so assets and navigation
// resolve correctly under the mount path.
BasePath string
// Logger receives one line per produced or copied file. Nil disables it.
Logger func(format string, args ...any)
// ExtraDirs maps URL mount paths to filesystems whose files are
// copied into the export under that path, e.g.
// {"/docs/api/sdk": os.DirFS("gen/sdk/dist")} so the SDK artifacts a
// live sdkdocs.Mount serves also ship in the static tree. Files the
// build (or the user static dir) already produced win: extra files
// are written only when absent, matching the SEO/PWA precedence.
ExtraDirs map[string]fs.FS
// ExcludeRoutes skips routes whose pattern (or a prefix segment of
// it) matches an entry, e.g. ExcludeRoutes: []string{"/broken"}
// skips "/broken/load" and every other /broken/* page. A lab or
// example app uses it to keep routes that fail ON PURPOSE out of
// the export set; the skip is logged so the gap is never silent.
// the builder refuses a page whose fill
// failed and was contained, so routes that fail on purpose must be
// excluded explicitly or the export errors.
ExcludeRoutes []string
// Handler, when set, serves the extra-script rail entries
// (uihost.WithExtraScripts) that the host does not own: a script an
// app serves from its own router, e.g. a reducer at
// /__site/livedash-reducers.js. Each such src is fetched through
// Handler and written into the export; one that does not answer 200
// fails the build, since every exported page would 404 on it.
// App.ExportStatic passes the app's router. A script this build
// already wrote (a framework asset, the static dir) is not fetched,
// nor is a src that is not a same-origin path (a CDN URL), nor a
// document-scoped script whose scope accepts no exported route.
Handler http.Handler
}
Builder generates a static-site snapshot from a UIHost.
func (*Builder) Build ¶
Build renders every reachable route to HTML and copies runtime/actions/static assets into b.OutDir. Returns a Result that lists what was produced.
func (*Builder) Watch ¶
func (b *Builder) Watch(ctx context.Context, watchDirs []string, interval time.Duration, onError func(error)) error
Watch invokes b.Build whenever a file under any of watchDirs changes its modification time, using a polling loop with the given interval. It runs one initial build immediately and returns when ctx is cancelled.
The loop ignores errors so a transient compile-time mistake in user code (e.g. a half-saved file) does not stop watching; the most recent error is passed to onError if non-nil. interval 0 keeps the 500ms default; a negative interval is rejected — a sign/unit error must not silently become a fast poll loop.
Polling avoids a third-party fsnotify dependency. For projects with a large source tree this is fine: we only stat files we already know about.
Source Files