Documentation
¶
Overview ¶
Package runtime provides the GoFastr client-side JavaScript runtime as an embedded resource. The runtime handles event delegation, component hydration on first interaction, and SSE listeners for server-driven islands.
Use RuntimeJS() to get the JavaScript source as a string, or RuntimeSize() to check the size of the runtime.
Package runtime ships the framework's client-side JavaScript runtime.
Two surfaces are exposed:
The bundled runtime (`runtime.js`) — the one-script payload that handles every framework primitive (dispatchRPC, SPA router, screen cache, signals, widgets, etc). Served at `/__gofastr/runtime.js`. This is the default surface.
Per-module bundles (`src/<name>.js`) — small payloads loaded on demand via `__gofastr.loadModule(name)`. Used for the optional code-splitting path; pages opt into individual modules instead of the bundled runtime when bundle size matters.
The HTTP server (core-ui/widget/server.go) consumes Module(name) + ModuleNames() to wire `/__gofastr/runtime/<name>.js` routes; the uihost emits `<link rel="modulepreload">` tags per page based on the components rendered on it.
Index ¶
- func ColorSchemeJS() (string, error)
- func DemandLoadModuleNames() []string
- func EmbedJS() (string, error)
- func EmbedLoaderJS() (string, error)
- func Module(name string) (string, bool)
- func ModuleNames() []string
- func ModuleSize(name string) int
- func MustEmbedJS() string
- func MustEmbedLoaderJS() string
- func MustRuntimeJS() string
- func MustStaticJS() string
- func NeededModules(pageHTML string) []string
- func RuntimeJS() (string, error)
- func RuntimeSize() int
- func StaticJS() (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ColorSchemeJS ¶
ColorSchemeJS returns the color-scheme bootstrap script — a tiny synchronous snippet meant to ship at the TOP of <head> so dark-mode CSS tokens take effect during the same first paint that hits the page. Reads localStorage("gofastr.colorScheme") + the OS prefers-color-scheme hint, then sets <html data-color-scheme="…"> and a matching <meta name="color-scheme">.
Apps that ship a theme toggle call `window.__gofastr_colorScheme.set('auto'|'light'|'dark')` to override the OS preference.
func DemandLoadModuleNames ¶
func DemandLoadModuleNames() []string
DemandLoadModuleNames returns the unique sorted list of every module referenced by the demand-load table. Used by tests to verify every declared module actually has a corresponding src/<name>.js file.
func EmbedJS ¶ added in v0.49.0
EmbedJS returns the `embed` runtime composition — the bundle served inside an embedded surface's iframe.
Its budget is looser than the core runtime's on purpose: it loads inside a frame and blocks nothing on the host page. It is still budgeted, because how fast an embed paints is the product.
func EmbedLoaderJS ¶ added in v0.49.0
EmbedLoaderJS returns the loader a customer pastes into their own page.
This is the tightest budget in the repo: it lands on a stranger's critical path, on a site whose performance we do not control and whose owner did not choose GoFastr. It creates the iframe, hands over the nonce by postMessage, and resizes. Anything else belongs inside the frame.
func Module ¶
Module returns the source of a single split runtime module by name (e.g. "fileupload"). Used by the HTTP server to serve /__gofastr/runtime/<name>.js. Returns "", false when the module is not embedded. Minified on first read (cached).
func ModuleNames ¶
func ModuleNames() []string
ModuleNames returns the sorted list of split modules currently embedded. Each name maps 1:1 to a /__gofastr/runtime/<name>.js URL.
func ModuleSize ¶
ModuleSize returns the byte size of a single embedded module, or 0 if the module isn't present. Used by tests asserting per-module size budgets.
func MustEmbedJS ¶ added in v0.49.0
func MustEmbedJS() string
MustEmbedJS returns the embed runtime or panics.
func MustEmbedLoaderJS ¶ added in v0.49.0
func MustEmbedLoaderJS() string
MustEmbedLoaderJS returns the embed loader or panics.
func MustRuntimeJS ¶
func MustRuntimeJS() string
MustRuntimeJS returns the bundled runtime or panics.
func MustStaticJS ¶ added in v0.48.0
func MustStaticJS() string
MustStaticJS returns the static runtime or panics.
func NeededModules ¶
NeededModules returns the deduplicated, sorted list of demand-load runtime modules whose marker substring appears in pageHTML. Used by the framework's UI host to emit <link rel="modulepreload"> tags in <head> per page, kicking off module fetches in parallel with the initial paint.
Matches are substring containment with an attribute-name boundary check — not a real HTML parse. The boundary check keeps one marker from matching inside a longer attribute name (data-fui-compute must not fire on data-fui-computed). The cost of a residual false positive is one wasted module fetch (no correctness impact).
func RuntimeJS ¶
RuntimeJS returns the composed runtime — the single-file IIFE every page ships by default. Assembled from the fragment files once, then minified (or returned verbatim when RUNTIME_NOMINIFY=1).
func StaticJS ¶ added in v0.48.0
StaticJS returns the `static` runtime composition — the bundle the SSG exporter (framework/static.Builder) serves for serverless deploys. Omits rpc (replaced by rpc-stub), sse, and compute: none function without the Go server behind them. widgets-boot is replaced by widgets-boot-static, which fetches the dumped /__gofastr/widgets.json catalog so data-fui-open overlays resolve against the static tree. Composed once at first read and cached (staticOnce), minified unless RUNTIME_NOMINIFY=1.
Types ¶
This section is empty.
Source Files
Directories