Documentation
¶
Overview ¶
Package transformer provides file-level and directory-level HTML transformation, walking HTML files on disk and expanding custom elements using the QJS rendering engine.
Index ¶
- func RenderFragment(input string, registry *jsengine.Registry, opts ...RenderOpts) (string, error)
- func RenderFragmentWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ...) (string, error)
- func RenderHTML(input string, registry *jsengine.Registry, opts ...RenderOpts) (string, error)
- func RenderHTMLWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ...) (string, error)
- type ElementRenderer
- type Options
- type RenderError
- type RenderOpts
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderFragment ¶
RenderFragment renders an HTML fragment.
func RenderFragmentWithEngine ¶
func RenderFragmentWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ignored map[string]bool, quiet ...bool) (string, error)
RenderFragmentWithEngine renders an HTML fragment using a caller-provided engine, avoiding engine creation overhead.
func RenderHTML ¶
RenderHTML takes an HTML string, finds custom elements, and returns the transformed HTML with Declarative Shadow DOM.
func RenderHTMLWithEngine ¶
func RenderHTMLWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ignored map[string]bool, quiet ...bool) (string, error)
RenderHTMLWithEngine transforms HTML using a caller-provided engine, avoiding engine creation overhead. Use this when you have a long-lived engine (e.g. in a Renderer).
Types ¶
type ElementRenderer ¶
type ElementRenderer interface {
LoadBundleForTag(tagName string, registry *jsengine.Registry) (bool, error)
RenderBatch(requests []jsengine.BatchRequest) ([]jsengine.BatchResult, error)
IsRegistered(tagName string) bool
}
ElementRenderer is the interface the transformer uses to load and render custom elements. *jsengine.Engine satisfies this interface. Defining it here decouples the HTML expansion logic from the concrete QJS runtime, allowing mock implementations in tests.
type Options ¶
type Options struct {
// DefsDir is the directory containing .golit.bundle.js files (Mode 1).
DefsDir string
// CompiledFile is a path to a single .golit.compiled.js artifact
// containing all bundles and a tag registry manifest.
CompiledFile string
// SourcesDir is a directory of component .js/.ts source files to bundle
// on-demand (Mode 2).
SourcesDir string
// ImportMapFile is a path to an import map JSON file (Mode 3).
ImportMapFile string
// AutoDiscover enables HTML auto-discovery of <script type="importmap">
// and <script type="module"> tags (Mode 4). Enabled by default when
// no other discovery mode is specified.
AutoDiscover bool
// Ignored is a set of custom element tag names to skip during SSR.
// These elements will be left as-is for client-side rendering only.
Ignored map[string]bool
// Preload is a list of extra JS modules to bundle and load into the
// QJS engine before component rendering. Each entry is a bare module
// specifier (e.g. "prism-esm") or a file path.
Preload []string
// Verbose prints progress information to stderr.
Verbose bool
// Quiet suppresses warnings to stderr (e.g. unregistered elements,
// render failures). Only errors are emitted.
Quiet bool
// DryRun reads and transforms files but does not write them back.
DryRun bool
// Concurrency is the number of parallel workers for file processing.
// 0 or 1 means sequential (default). Set to runtime.NumCPU() or
// a specific value for parallel processing of large sites.
Concurrency int
// OutDir is an optional output directory. When set, transformed files
// are written here instead of modifying the input files in-place.
OutDir string
// Isolate creates a fresh QJS context per HTML file, clearing all
// global state between files. Slower but safer for untrusted components.
Isolate bool
// Registry is an optional pre-populated bundle registry. When set,
// TransformDir uses it instead of creating a new one. Additional
// discovery modes (DefsDir, SourcesDir, etc.) still layer onto it.
Registry *jsengine.Registry
}
Options configures the transformer.
type RenderError ¶
RenderError records a custom element that failed to render during SSR.
func (RenderError) Error ¶
func (e RenderError) Error() string
type RenderOpts ¶
RenderOpts configures optional behavior for RenderHTML and RenderFragment.
type Result ¶
type Result struct {
FilesProcessed int
FilesModified int
Errors []error
RenderErrors []RenderError
Unregistered []string
}
Result holds stats from a transform run.
func TransformDir ¶
TransformDir processes all HTML files in a directory tree.
Processing happens in two passes:
- Discovery (sequential): read every HTML file and run component auto-discovery so the registry is fully populated.
- Render (parallel when Concurrency > 1): transform files using a pool of QJS engines, one engine per worker goroutine.