Documentation
¶
Overview ¶
Package renderx implements the SSR render pipeline (QuickJS engine pool, bundle build, prerender, cache, SEO companions).
This file owns the pipeline's TanStack Router SSR affordances. The JavaScript source of truth for both values below is packages/runtime/src/router-tanstack.tsx:
- PRELUDE_SHIMS — the QuickJS prelude addendum (URLSearchParams + AbortController) every TanStack SSR bundle needs before it evaluates.
- ESBUILD_ALIASES — the esbuild alias pinning @tanstack/router-core/isServer to the server variant. The default (client) variant evaluates `window?.origin` inside the sandbox, where window is deliberately never defined, and crashes the render.
The Go render pipeline must carry an executable copy of both: it builds the prelude string and the esbuild alias map natively, so a TS-only constant cannot reach it. Keeping that copy here (rather than in every product) exists because the alternative is a hand-maintained mirror per TanStack consumer: the TS runtime moves, the product copy does not, and the product silently runs an outdated shim with zero detection (exactly what happened in v0.10.1). Products import renderx.TanstackPrelude and renderx.AppendTanstackAliases instead of mirroring the constants.
tanstack_test.go is the drift guard: it parses router-tanstack.tsx and fails when this file diverges from the TS source. The framework repo is where drift can happen, so the guard runs there; from a module cache (no packages/ checkout) it skips.
Index ¶
- Constants
- Variables
- func AffectedPatterns(pattern string) []string
- func AppendTanstackAliases(base map[string]string, webDir string) map[string]string
- func BuildSSRBundle(opts BuildOptions) ([]byte, error)
- func DefaultPoolSize() int
- func DefaultSSRAliases(webDir, packagesDir string) map[string]string
- func ExpandPath(pattern string, params Params) (string, bool)
- func Handler(deps HandlerDeps) http.Handler
- func IndexNow(ctx context.Context, deps IndexNowDeps, urls []string) error
- func Invalidate(ctx context.Context, pattern string, params Params) error
- func PropsSHA256(propsJSON []byte) string
- func Reconcile(routes []RouteSpec) error
- func ReconcileEngine(ctx context.Context, r Renderer) error
- func Refresh(ctx context.Context, pattern string, params Params) error
- func RegisterDep(pagePattern, dependsOnPattern string)
- func RegisterLoader(pattern string, fn LoaderFn)
- func RegisterPaths(pattern string, fn PathsFn)
- func RegisterService(s *Service)
- func RenderDocument(doc Document) ([]byte, error)
- func ResetForTest()
- func RobotsHandler(opts RobotsOptions) http.Handler
- func SitemapHandler(routes []RouteSpec, baseURL string, opts SitemapOptions) http.Handler
- func TanstackPrelude() string
- func ValidParamValue(v string) bool
- func ValidateParams(p Params) error
- func ViteBuildID(data []byte) string
- func ViteManifestFiles(data []byte) ([]string, error)
- type BuildOptions
- type CacheConfig
- type CacheEntry
- type DevHandler
- type DevHandlerDeps
- type Directive
- type DirectiveSink
- type Document
- type EnginePool
- type HandlerDeps
- type HeadEntry
- type Hydrate
- type IndexNowDeps
- type LayeredCache
- func (c *LayeredCache) Delete(ctx context.Context, paths ...string) error
- func (c *LayeredCache) EvictMatching(ctx context.Context, match func(key string) bool) (int, error)
- func (c *LayeredCache) Get(ctx context.Context, path string) (CacheEntry, bool)
- func (c *LayeredCache) GetOrLoad(ctx context.Context, path string, ...) (CacheEntry, error)
- func (c *LayeredCache) GetOrLoadHit(ctx context.Context, path string, ...) (CacheEntry, bool, error)
- func (c *LayeredCache) GetStale(ctx context.Context, path string) (CacheEntry, bool)
- func (c *LayeredCache) Keys() []string
- func (c *LayeredCache) PurgeForeign(ctx context.Context, buildID string) error
- func (c *LayeredCache) Put(ctx context.Context, path string, ent CacheEntry) error
- type LoaderFn
- type Mode
- type PagePath
- type Params
- type PathsFn
- type PoolOptions
- type PrerenderDeps
- type PrerenderManifest
- type PrerenderManifestEntry
- type Registry
- func (r *Registry) AffectedPatterns(pattern string) []string
- func (r *Registry) LookupLoader(pattern string) (LoaderFn, error)
- func (r *Registry) LookupPaths(pattern string) (PathsFn, error)
- func (r *Registry) Reconcile(routes []RouteSpec) error
- func (r *Registry) RegisterDep(pagePattern, dependsOnPattern string)
- func (r *Registry) RegisterLoader(pattern string, fn LoaderFn)
- func (r *Registry) RegisterPaths(pattern string, fn PathsFn)
- type RenderResult
- type Renderer
- type RobotsOptions
- type RouteSpec
- type SEOSignals
- type Service
- type ShellHead
- type SitemapOptions
- type UnknownPathPolicy
- type ViteAssets
Constants ¶
const ( DefaultMemPages = 1024 DefaultTTL = time.Hour )
const ( DefaultMemoryLimit = 512 << 20 // WasmShadowStackSize is the physical C shadow stack baked into the // bundled quickjs.wasm at build time (wasm-ld -z stack-size=8MiB; see // internal/qjs/csrc/README.md). Exhausting it traps the wasm module with // an uncatchable "out of bounds memory access" and leaves the instance // unusable — QuickJS's own catchable guard must trip first, which is why // MaxStackSize is validated against this ceiling minus headroom. WasmShadowStackSize = 8 << 20 // MaxLogicalStackSize is the largest accepted PoolOptions.MaxStackSize: // the shadow stack minus a 1MiB headroom, so a guard trip on the deepest // legal budget still leaves real stack below it and the physical wall // stays unreachable by recursion. MaxLogicalStackSize = WasmShadowStackSize - 1<<20 // DefaultMaxStackSize is the QuickJS execution-stack cap applied when // PoolOptions.MaxStackSize is unset. QuickJS checks it on every nested // call and raises a CATCHABLE "Maximum call stack size exceeded" that // leaves the instance healthy (measured capacities: ~3.1k frames of // simple recursion at this budget, ~8k at MaxLogicalStackSize). History: // the pre-v0.17.0 engine silently disabled this guard under wasi, so the // only visible wall was the binary's 64KiB default shadow stack — the // original #15/#16 "phantom depth ceiling". Rebuilt wasm (csrc/, pinned // quickjs-ng v0.17.0) restores the guard; see ADR 0015. DefaultMaxStackSize = 1 << 20 DefaultRenderTimeout = 3 * time.Second )
const ( DefaultCacheControl = "max-age=60, stale-while-revalidate=300" DefaultPoisonTTL = 10 * time.Minute )
const ( TierEmbed = "embed" TierCache = "cache" TierRender = "render" TierStale = "stale" TierSPA = "spa" TierAsset = "asset" TierError = "error" TierRobots = "robots" TierSitemap = "sitemap" )
Tier values, most-specific-first in the serving order: embedded prerender artifact, layered-cache hit, on-the-spot render (miss path), stale copy on render failure, SPA shell fallback (index.html routes incl. the 404 form), static asset passthrough, product error page. The SEO companions carry their own values so traffic middleware can count crawler fetches of them.
const DefaultIndexNowEndpoint = "https://api.indexnow.org/indexnow"
const DefaultPrelude = `` /* 5289-byte string literal not displayed */
const HeaderTier = "X-Renderx-Tier"
HeaderTier names the response header carrying which serving layer produced the response — one of the Tier* values below. It exists for traffic observation (metrics.TrafficConfig consumes it: "did the crawler get cache or SSR?") and for debugging ("why was this request rendered?"). Readers must keep in mind that a CDN caching the HTML replays the header of the origin response that first populated the cache.
const MaxPropsBytes = 512 << 10
const OutputVersion = "rv1"
Variables ¶
var ( ErrRenderTimeout = errors.New("renderx: render timeout") ErrPoolClosed = errors.New("renderx: engine pool closed") )
var ( ErrEmptyRenderOutput = errors.New("renderx: empty render output") ErrMissingTitle = errors.New("renderx: head directives emitted but no <title>") // ErrServerSuspense marks output that contains React's client-rendering // fallback marker. renderToString does NOT wait for Suspense: a page that // lazily imports anything on its render path produces // `<!--$!--><template ...><!--/$-->` instead of the component's markup, and // the document is non-empty — so the empty-output assertion (A2) cannot see // it. Without this check the failure ships as "page renders blank in // production" (the marker is invisible in a browser, and the template // content is the only clue). ErrServerSuspense = errors.New("renderx: page suspended during server render (lazy import inside a static route?)") )
var ( ErrPatternNotFound = errors.New("renderx: pattern not registered") ErrPatternMismatch = errors.New("renderx: registered pattern not in route table") ErrMissingPaths = errors.New("renderx: static param route missing Paths") ErrInvalidParam = errors.New("renderx: invalid path param") ErrInvalidDirective = errors.New("renderx: invalid directive payload") ErrInvalidHeadTag = errors.New("renderx: invalid head tag or attr name") ErrInvalidCacheKey = errors.New("renderx: invalid cache key") ErrBuildIDMismatch = errors.New("renderx: cache entry buildId mismatch") ErrPropsTooLarge = errors.New("renderx: props exceed size limit") ErrPageNotFound = errors.New("renderx: page not found") )
Functions ¶
func AffectedPatterns ¶
func AppendTanstackAliases ¶ added in v0.10.2
AppendTanstackAliases adds the isServer alias (the Go side of the TS-side ESBUILD_ALIASES) on top of base, resolving the target against the same node_modules tree the rest of the SSR build reads: the web app's own node_modules first, then the npm-workspaces hoist root (webDir/../../node_modules — a web app that is a workspace member usually resolves @tanstack/router-core at the repo root). TanStack-agnostic callers can ignore the extra entry; the returned map is base.
func BuildSSRBundle ¶
func BuildSSRBundle(opts BuildOptions) ([]byte, error)
func DefaultPoolSize ¶
func DefaultPoolSize() int
func DefaultSSRAliases ¶
func Handler ¶
func Handler(deps HandlerDeps) http.Handler
func PropsSHA256 ¶
func RegisterDep ¶
func RegisterDep(pagePattern, dependsOnPattern string)
func RegisterLoader ¶
func RegisterPaths ¶
func RegisterService ¶
func RegisterService(s *Service)
func RenderDocument ¶
func ResetForTest ¶
func ResetForTest()
func RobotsHandler ¶ added in v0.7.2
func RobotsHandler(opts RobotsOptions) http.Handler
RobotsHandler serves /robots.txt: one "User-agent: *" group with the configured Disallow prefixes, the extra verbatim lines, and the Sitemap pointer. Options are validated and serialized once at construction — a malformed option panics at wiring time, never serving a silently wrong file.
func SitemapHandler ¶
func SitemapHandler(routes []RouteSpec, baseURL string, opts SitemapOptions) http.Handler
SitemapHandler serves /sitemap.xml from the route table + Paths registry. baseURL must be an absolute http(s) origin (e.g. "https://example.com") — a malformed value panics at construction time; mount the route only when an origin is actually known (see example wiring for the env-driven pattern).
func TanstackPrelude ¶ added in v0.10.2
func TanstackPrelude() string
TanstackPrelude returns the engine prelude for TanStack SSR bundles: the renderx default prelude plus the TanStack shims (the Go side of PRELUDE_SHIMS). Pass it as PoolOptions.Prelude:
renderx.NewEnginePool(bundle, renderx.PoolOptions{Prelude: renderx.TanstackPrelude()})
func ValidParamValue ¶
func ValidateParams ¶
func ViteBuildID ¶
func ViteManifestFiles ¶ added in v0.12.0
ViteManifestFiles returns every file path the build emitted, slash-prefixed and sorted, for use as an authoritative content-addressed asset list (webx.AssetCacheManifest).
Why this exists instead of relying on a filename heuristic: a build's manifest knows exactly which URLs carry a content hash, while any name-based rule has to guess and has a false-positive class that silently pins a replaceable file for a year (`Some-Page-Banner.png` looks like a hash; `CYhS-pAS` — a real hash — does not look like one to a tighter rule).
Every value's `file` and `css` are collected. Note that Vite lists the file relative to the build root, so no path cleaning beyond the leading slash is performed here.
Types ¶
type BuildOptions ¶
type CacheConfig ¶
type CacheEntry ¶
type CacheEntry struct {
HTML []byte `json:"html"`
PropsSHA256 string `json:"props_sha256"`
BuiltAt time.Time `json:"built_at"`
BuildID string `json:"build_id"`
}
func RenderOnce ¶ added in v0.4.0
func RenderOnce(ctx context.Context, r Renderer, pageID, location string, props json.RawMessage, lang string, assets ViteAssets, hydrate Hydrate) (CacheEntry, error)
RenderOnce 把单个页面渲染成完整 HTML 文档——不经过缓存与 HTTP 层的 一次性渲染入口,预渲染 / handler 未命中 / 缓存回填共用此组装。 预览(草稿渲染)、邮件合成、调试等场景直接调用即可,语义与预渲染管线 完全一致(props 规范化、空输出校验、head 指令与 <title> 校验)。 assets.Shell / assets.BaseURL 随 assets 一起生效:壳 head 继承与 og:image/twitter:image/og:url/canonical 绝对化对直接调用方同样成立(壳只需 解析一次挂到 assets 上,无需在每条组装路径单独接线)。
hydrate=none 的页面不注入 props 脚本与水合入口:两者唯一的消费者都是 客户端入口,没有它就没有意义——留在 HTML 里只会把 props 白发给所有人, 还会让缓存条目随 props 变化而失效。
type DevHandler ¶
type DevHandler struct {
// contains filtered or unexported fields
}
func NewDevHandler ¶
func NewDevHandler(deps DevHandlerDeps) (*DevHandler, error)
func (*DevHandler) Close ¶
func (d *DevHandler) Close()
func (*DevHandler) ServeHTTP ¶
func (d *DevHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type DevHandlerDeps ¶
type DevHandlerDeps struct {
BuildOpts BuildOptions
PoolOpts PoolOptions
NewRenderer func(bundle []byte, opts PoolOptions) (Renderer, error)
Cache *LayeredCache
Routes []RouteSpec
BuildID string
Assets ViteAssets
Lang string
SPA http.Handler
Registry *Registry
Interval time.Duration
Warn func(format string, args ...any)
}
type Directive ¶
type Directive struct {
Kind string `json:"kind"`
Payload json.RawMessage `json:"payload,omitempty"`
Seq int `json:"seq"`
}
type DirectiveSink ¶
type DirectiveSink struct {
// contains filtered or unexported fields
}
func NewSink ¶
func NewSink() *DirectiveSink
func (*DirectiveSink) Append ¶
func (s *DirectiveSink) Append(kind string, payload json.RawMessage) Directive
func (*DirectiveSink) Directives ¶
func (s *DirectiveSink) Directives() []Directive
func (*DirectiveSink) Truncated ¶
func (s *DirectiveSink) Truncated() bool
type Document ¶
type Document struct {
Lang string
Head []HeadEntry
CSS []string
BodyHTML string
PropsJSON []byte
PageID string
HydrateScript string
// NoHydration 为真时不写 props 脚本。props 脚本唯一的消费者是客户端
// 入口;没有入口的文档里它只是把页面数据白发给每个访客(hydrate=none
// 的零 JS 页),所以两者必须同进同退。
NoHydration bool
// InheritHead holds shell-level head entries (favicon links,
// theme-color, rel=modulepreload …) that RenderDocument emits between the
// viewport fallback and the page's own Head, before stylesheets — earlier
// than CSS so preload/modulepreload hints are discovered early (F-4).
// Entries whose (tag, rel/name/property) key collides with a page Head
// entry are skipped: the page always wins over the shell. Typical source:
// ParseShellHead, carried on ViteAssets.Shell by RenderOnce.
InheritHead []HeadEntry
// HTMLAttrs / BodyAttrs are extra attributes for the <html> / <body>
// open tags (e.g. style="background:…" from the shell to prevent FOUC).
// On <html> the lang attribute is ignored — Lang owns it.
HTMLAttrs map[string]string
BodyAttrs map[string]string
// BaseURL, when set to an absolute http(s) origin, turns relative
// og:image / twitter:image / og:url content values and relative
// link[rel=canonical] href values into absolute URLs (social scrapers
// drop relative values; a relative canonical is legal, but absolute is
// unambiguous — third-party SEO tooling and citation credit key on the
// literal URL, so the assembly step removes the split). Already-absolute
// values and every other meta/link are untouched, and an empty or
// non-absolute BaseURL disables the rewrite entirely.
// This covers only the server-rendered first HTML; client-side head
// updates after SPA navigation keep whatever the page emits (deliberate
// boundary: crawlers read the first HTML only).
BaseURL string
}
type EnginePool ¶
type EnginePool struct {
// contains filtered or unexported fields
}
func NewEnginePool ¶
func NewEnginePool(bundle []byte, opts PoolOptions) (*EnginePool, error)
func (*EnginePool) Close ¶
func (p *EnginePool) Close()
func (*EnginePool) Render ¶
func (p *EnginePool) Render(ctx context.Context, pageID, location string, props json.RawMessage) (RenderResult, error)
type HandlerDeps ¶
type HandlerDeps struct {
PrerenderFS fs.FS
SPA http.Handler
Cache *LayeredCache
Renderer Renderer
Routes []RouteSpec
BuildID string
CacheControl string
ErrorPage func(http.ResponseWriter, *http.Request, error)
Warn func(format string, args ...any)
Assets ViteAssets
Lang string
Registry *Registry
PoisonTTL time.Duration
// UnknownPath selects the unmatched-path policy (see UnknownPathPolicy).
// Zero value keeps the v0.15.0 behavior: SPA shell with 200.
UnknownPath UnknownPathPolicy
// ShellMeta is injected into the <head> of every SPA shell response —
// both the plain fallback (spa) and its notFoundWriter-wrapped 404 form.
// The typical use is declaring the shell pages "not indexable" once for
// the whole site:
//
// ShellMeta: []renderx.HeadEntry{{
// Tag: "meta",
// Attrs: map[string]string{"name": "robots", "content": "noindex, follow"},
// }},
//
// Entries go through the same whitelist as renderer head directives
// (renderHeadEntry: tag/attr name rules, deny script/iframe/base,
// deny http-equiv) and a malformed entry panics at Handler construction.
// Full-document responses (embed/cache/render tiers) never get ShellMeta —
// they carry their own head.
ShellMeta []HeadEntry
}
type HeadEntry ¶
type HeadEntry struct {
Tag string `json:"tag"`
Attrs map[string]string `json:"attrs,omitempty"`
Children string `json:"children,omitempty"`
}
func HeadEntries ¶
type Hydrate ¶ added in v0.12.0
type Hydrate string
Hydrate 是路由表投影里的第二根轴(与 Mode 正交):服务端产出的 HTML 之后还要不要 JS。空串按 HydrateLoad 处理,旧路由表不声明该字段时行为 不变。
type IndexNowDeps ¶
type LayeredCache ¶
type LayeredCache struct {
// contains filtered or unexported fields
}
func NewLayeredCache ¶
func NewLayeredCache(cfg CacheConfig) (*LayeredCache, error)
func (*LayeredCache) Delete ¶
func (c *LayeredCache) Delete(ctx context.Context, paths ...string) error
func (*LayeredCache) EvictMatching ¶
func (*LayeredCache) Get ¶
func (c *LayeredCache) Get(ctx context.Context, path string) (CacheEntry, bool)
func (*LayeredCache) GetOrLoad ¶
func (c *LayeredCache) GetOrLoad(ctx context.Context, path string, load func(context.Context) (CacheEntry, error)) (CacheEntry, error)
func (*LayeredCache) GetOrLoadHit ¶ added in v0.7.2
func (c *LayeredCache) GetOrLoadHit(ctx context.Context, path string, load func(context.Context) (CacheEntry, error)) (CacheEntry, bool, error)
GetOrLoadHit is GetOrLoad plus a hit report: hit=true when an existing cache entry (memory or disk) was served — including the singleflight replay path, where a concurrent Put landed after this request's first check and the load never ran. hit=false when the request was answered through the load path (this request's own load, or a coincident one it joined as a singleflight waiter). The X-Renderx-Tier response header is built on it.
func (*LayeredCache) GetStale ¶
func (c *LayeredCache) GetStale(ctx context.Context, path string) (CacheEntry, bool)
func (*LayeredCache) Keys ¶
func (c *LayeredCache) Keys() []string
func (*LayeredCache) PurgeForeign ¶
func (c *LayeredCache) PurgeForeign(ctx context.Context, buildID string) error
func (*LayeredCache) Put ¶
func (c *LayeredCache) Put(ctx context.Context, path string, ent CacheEntry) error
type PoolOptions ¶
type PoolOptions struct {
Size int
MemoryLimit int
// MaxStackSize caps the QuickJS execution stack in bytes. QuickJS's
// guard trips BEFORE the wasm module's physical shadow stack and raises
// a catchable "Maximum call stack size exceeded" — the instance stays
// healthy — so this knob trades depth capacity against per-render stack
// budget. Values above MaxLogicalStackSize are rejected at construction:
// beyond it recursion could reach the physical wall (uncatchable trap,
// instance retired). 0 keeps DefaultMaxStackSize (1MiB).
MaxStackSize int
RenderTimeout time.Duration
Prelude string
}
type PrerenderDeps ¶
type PrerenderManifest ¶
type PrerenderManifest struct {
BuildID string `json:"buildId"`
GeneratedAt time.Time `json:"generatedAt"`
Pages []PrerenderManifestEntry `json:"pages"`
}
func Prerender ¶
func Prerender(ctx context.Context, deps PrerenderDeps) (PrerenderManifest, error)
type PrerenderManifestEntry ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func NewRegistry ¶
func NewRegistry() *Registry
func (*Registry) AffectedPatterns ¶
func (*Registry) RegisterDep ¶
func (*Registry) RegisterLoader ¶
func (*Registry) RegisterPaths ¶
type RenderResult ¶
type RenderResult struct {
HTML string
Sink *DirectiveSink
}
type RobotsOptions ¶ added in v0.7.2
type RobotsOptions struct {
// SitemapURL is emitted as a "Sitemap:" line when non-empty (pass an
// absolute URL, e.g. "https://example.com/sitemap.xml").
SitemapURL string
// Disallow lists path prefixes emitted as "Disallow:" lines under the
// default "User-agent: *" group (e.g. "/api/", "/admin").
Disallow []string
// Extra holds verbatim lines appended after the default block, for more
// elaborate rules (further user-agent groups, Allow exceptions). Blank
// lines are skipped.
Extra []string
}
RobotsOptions configures RobotsHandler.
type SEOSignals ¶ added in v0.7.2
type SEOSignals struct {
Title string
Description string
Canonical string
// CanonicalCount counts link[rel=canonical] elements (>1 = the page emits
// duplicates). The SSR path does not dedupe head entries — one page, one
// canonical is a product-side rule, and build-time audits warn on it.
CanonicalCount int
}
SEOSignals is the head-level SEO signal set AuditSEO extracts from a rendered document. Empty strings mean the signal is absent.
func AuditSEO ¶ added in v0.7.2
func AuditSEO(doc []byte) SEOSignals
AuditSEO extracts the title / meta description / canonical link from a rendered document. It understands the serialization this package's template emits (lowercase tags, double-quoted attributes) — it audits our own output, not arbitrary HTML. Values come back HTML-unescaped. Build chains use it to report SEO coverage of prerendered pages (cmd/render does).
type Service ¶
type Service struct {
Cache *LayeredCache
Renderer Renderer
Routes []RouteSpec
BuildID string
Assets ViteAssets
Lang string
Registry *Registry
Warn func(format string, args ...any)
RefreshTimeout time.Duration
// contains filtered or unexported fields
}
func (*Service) Invalidate ¶
type ShellHead ¶ added in v0.18.0
type ShellHead struct {
// HeadTags are the shell's <link> and <meta> tags after exclusion (see
// ParseShellHead): stylesheets, meta charset, meta viewport and <title>
// never appear here — each has its own channel (Document.CSS, the
// mandatory charset line, the viewport fallback, the page's own title).
HeadTags []HeadEntry
// HTMLAttrs are the attributes of the shell's <html> open tag minus
// `lang` (Document.Lang owns lang).
HTMLAttrs map[string]string
// BodyAttrs are the attributes of the shell's <body> open tag, verbatim.
BodyAttrs map[string]string
}
ShellHead carries the pieces of the Vite shell (web/dist/index.html) that RenderDocument must inherit when it rebuilds a document from scratch. RenderDocument does not rewrite the shell; it composes a fresh document, so anything that only lives in the shell head (favicon links, theme-color, modulepreload hints) and the html/body open-tag attributes (e.g. a warm background color that prevents FOUC) would otherwise be dropped on every prerendered and SSR-rendered page. The product parses the shell once at startup (or once per prerender run) and attaches the result to ViteAssets.
func ParseShellHead ¶ added in v0.18.0
ParseShellHead extracts ShellHead from a Vite shell document. It is a pure function that never fails: a missing head, missing tags or attributes, or tags the head-entry whitelist would reject all degrade to "not inherited" (empty/absent results) rather than erroring — the shell is build output the framework does not control, and a quirky shell must never block rendering.
Exclusion rules (each excluded kind has a dedicated, overridable channel):
- <link> whose rel token list contains "stylesheet" — CSS goes through Document.CSS (the manifest-derived, deduplicated list);
- <meta charset> — RenderDocument always writes its own charset line;
- <meta name="viewport"> — covered by the viewport fallback and its page-head override rule;
- everything that is not <link> or <meta> (<title>, <script>, …) — the page owns its title, and scripts have their own injection channel.
Everything else is kept, including rel=modulepreload, rel=icon, rel=preconnect and meta name=theme-color.
type SitemapOptions ¶
type SitemapOptions struct {
Filter func(route RouteSpec, location string, params Params) bool
// Lastmod optionally reports the last-modified time for one sitemap URL.
// location is the root-relative path ("/blog/hello"); params carries the
// expanded route params (nil for parameterless routes). It runs per URL
// during sitemap generation and may do I/O (that is its purpose), hence
// the ctx — return ok=false to omit <lastmod> for that URL (unknown slug,
// lookup failure: the entry degrades to loc-only, never a 500). Emitted
// as a W3C date (YYYY-MM-DD, UTC-normalized) per sitemaps.org.
Lastmod func(ctx context.Context, route RouteSpec, location string, params Params) (time.Time, bool)
Registry *Registry
}
type UnknownPathPolicy ¶ added in v0.16.0
type UnknownPathPolicy string
UnknownPathPolicy selects what the handler does with a GET/HEAD path that matched no static route and hit no embedded prerender snapshot — the SPA fallback decision at the bottom of ServeHTTP.
const ( // UnknownPathSPAShell serves the SPA shell with status 200 — the v0.15.0 // behavior and still the zero-value default, so existing deployments keep // serving their CSR routes (e.g. /login) without touching wiring. // // NOTE: this default is kept for compatibility only, and new deployments // are recommended to migrate to UnknownPathNotFound. SPA-fallback-200 // turns every garbage URL (/random-page, /zh/fake, trailing-slash twins) // into an indexable soft-404 — the shell has no canonical, no noindex and // a generic title, and crawlers collect them (field report: // braceletmakeronline.com, GSC exposure on shell URLs). Products that // need a real 200 on specific CSR paths (they are app pages, not content) // should mount those paths ahead of renderx — registering them as ModeCSR // in the route table does NOT create a serving exemption (ModeCSR is // projection metadata: sitemap excludes non-static routes either way); // every non-static path flows through this policy. UnknownPathSPAShell UnknownPathPolicy = "spa-shell" // UnknownPathNotFound downgrades the SPA shell DOCUMENT to 404 via // notFoundWriter: human visitors still get the shell bytes (their client // router boots and renders the route) and crawlers see an honest 404 // instead of an indexable thin shell. Static files the SPA handler // serves for real (assets, favicon) keep their genuine statuses — only // the HTML shell document is downgraded (audit P0 2026-10-26: an // earlier draft 404'd assets too, killing hydration site-wide). UnknownPathNotFound UnknownPathPolicy = "not-found" )
type ViteAssets ¶
type ViteAssets struct {
CSS []string
JS []string
// Shell carries the parsed Vite shell (dist/index.html) so every document
// assembled from these assets inherits the shell's head entries (favicon
// links, theme-color, rel=modulepreload — F-4/S-1/S-5 family) and its
// <html>/<body> attributes (background color vs FOUC). Zero value = no
// inheritance; typical wiring is one ParseShellHead call attached here.
Shell ShellHead
// BaseURL is the absolute http(s) origin the build is served under
// (usually the PUBLIC_BASE_URL env). When set, RenderOnce turns relative
// og:image / twitter:image / og:url content values and relative
// link[rel=canonical] href values into absolute URLs; empty or malformed
// values disable the rewrite (no-op).
BaseURL string
}
func ParseViteManifest ¶
func ParseViteManifest(data []byte, entryKey string) (ViteAssets, error)