vue-lynx/plugin / PluginVueLynxOptions
#Interface: PluginVueLynxOptions
Options for pluginVueLynx.
#Properties
| Property | Type | Default value | Description | Defined in |
|---|---|---|---|---|
optionsApi? | boolean | true | Whether to enable Vue's Options API support. Disabling it reduces bundle size. | index.ts:70 |
prodDevtools? | boolean | false | Whether to enable Vue devtools in production builds. | index.ts:76 |
enableCSSSelector? | boolean | true | Whether to enable CSS selector support in the Lynx template. When enabled, CSS from Vue <style> blocks and imported CSS files will be compiled into the Lynx bundle and applied via class selectors. | index.ts:84 |
enableCSSInheritance? | boolean | false | Whether to enable CSS inheritance in the Lynx engine. When enabled, CSS property values (including CSS custom properties / variables) cascade from parent elements to children, matching standard CSS behavior. Required for design-token patterns where CSS variables are set on a parent and consumed by descendants. | index.ts:94 |
customCSSInheritanceList? | string[] | undefined | A list of additional CSS properties to inherit beyond the engine defaults. Only effective when enableCSSInheritance is true. | index.ts:101 |
enableCSSInlineVariables? | boolean | false | Whether to enable CSS custom properties (variables) in inline styles. When enabled, setting --* properties via :style bindings will be recognized by the Lynx engine at runtime. | index.ts:109 |
debugInfoOutside? | boolean | true | Whether to place debug info outside the template bundle. Reduces template size in dev builds. | index.ts:116 |
autoPixelUnit? | boolean | true | Whether to automatically append 'px' to numeric style values (e.g. fontSize: 24 → '24px'). Dimensionless properties like flex, opacity, and zIndex are never converted. This convenience behavior is deprecated and will default to false in the next major version. Prefer explicit string units (e.g. fontSize: '24px'). Deprecated Will default to false in the next major version. | index.ts:130 |
enableElementTemplates? | boolean | enableIFR | Whether to enable element templates (compile-time template lowering). Eligible template subtrees — plain elements with compile-time-known structure — are lowered into "element templates": the static skeleton becomes a straight-line element-creation function executed on the main thread via a single INSTANTIATE_TEMPLATE op, and interior dynamic parts ("holes") receive deterministic ids updated through the ordinary ops. This removes the per-static-node vdom/ops/interpreter cost on first render and shrinks the cross-thread payload — for both the normal pipeline and IFR (they compose). Structural features (components, v-if/v-for hosts, slots, refs, directives, <list>) always stay on the normal vdom path; lowering is purely an optimization and never changes rendering semantics. Defaults to the value of enableIFR: enabling IFR also enables element templates unless this option is explicitly set to false. It can still be enabled independently when IFR is off. | index.ts:154 |
templateNaming? | "block" | "node" | "dense" | "sparse" | 'block' | Axis B — naming: which slots of a materialized template subtree receive cross-thread identities (see vue-lynx/internal/matrix). - 'block' — the template block is the naming unit (one base id + offsets): Vapor CLONE_TREE becomes a Data-Template when __vlxAddressing is present, with fail-safe fallback to node naming. - 'node' — every preorder slot is named independently: the Vapor Named Tree cell, used for A/B measurement in the graph-eng matrix. Legacy spellings 'sparse' ≡ 'block', 'dense' ≡ 'node' are accepted. Has no effect on VDOM (Code-Template naming is intrinsically block-unit). | index.ts:172 |
templateStaging? | | "code" | "data" | "ops" | "native" | "opstream" | "tree" | "engine" | undefined (per-render-model default above) | Axis A — staging: what form the compiled template residual exists in on the main thread (see vue-lynx/internal/matrix). - 'ops' (interp) — per-instruction stream, no template mechanism (VDOM default without element templates). - 'data' (interp) — serialized tree shipped as data + one generic MT interpreter (REGISTER_TREE/CLONE_TREE; Vapor default → Data-Template). - 'code' (compiled) — per-template compiled create() closure, no interpreter (INSTANTIATE_TEMPLATE → Code-Template). For Vapor (#337, +b:c): the plugin parses each template() HTML string at build time, bakes a straight-line-PAPI create() into the MT bundle, and instantiation crosses the wire as a single INSTANTIATE_TEMPLATE(id). Guarded by the structure-fingerprint fail-safe — any build↔runtime parse disagreement silently falls back to the 'data' path per template. - 'native' (compiled) — host-resident Engine-Template: the MT executor routes instantiation through the __CreateElementTemplate PAPI family when the engine provides it, and falls back to interpretation (reported N/A/stub) when it does not. Legacy spellings 'opstream' ≡ 'ops', 'tree' ≡ 'data', 'engine' ≡ 'native' are accepted. Defaults preserve current behavior: Vapor → 'data'; VDOM → 'code' when element templates are enabled, else 'ops'. | index.ts:203 |
templateDelivery? | "bundle" | "runtime" | 'runtime' | Delivery — when the template residual reaches the main thread (the sixth coordinate column; #338, +b!). - 'runtime' — today's default: Vapor structures ship over the wire once per template (REGISTER_TREE). - 'bundle' — the build-time-parsed structure AST is baked into the MT bundle (registerVaporStructure(hash, ast)); the BG sends only the fingerprint hash (REGISTER_TREE_BUNDLE) when its runtime parse hashes identically, and falls back to the full REGISTER_TREE otherwise. Flips ONLY the delivery column: interpretation, naming and the whole update path are byte-identical to the 'runtime' cell. Only meaningful for Vapor 'data' staging ('code' staging always rides the bundle; VDOM code templates already do). | index.ts:230 |
ifrPaint? | | "plain" | "code-paint" | "native-paint" | "disposable-et" | "engine-et" | 'plain' | Axis D — IFR paint mode: how the ephemeral first-frame copy materializes templates when enableIFR is on. - 'plain' — today's behavior: the recorded op stream paints via the same staging as the durable tree. - 'code-paint' (legacy 'disposable-et') — first frame paints through the registered Code-Template create() executors (ephemeral Code-Template). - 'native-paint' (legacy 'engine-et') — first frame routes through the Engine-Template family when available (N/A/stub fallback otherwise). | index.ts:247 |
enableSparseNaming? | boolean | true | Whether Vapor CLONE_TREE may use sparse A2 naming. Deprecated Use templateNaming (false ≡ 'dense'). When both are set, templateNaming wins. | index.ts:261 |
enableIFR? | boolean | false | Whether to enable IFR (Instant First-Frame Rendering). When enabled, the main-thread bundle contains the full Vue runtime and app code (instead of only worklet registrations). The first screen is rendered synchronously on the main thread during loadTemplate — before any background JavaScript runs — eliminating the blank-frame gap. When the background thread boots, its initial render is hydrated against the main-thread output instead of being re-applied. Constraints (matching ReactLynx IFR): - First-screen render output must be deterministic and thread-agnostic (no Math.random() / Date.now() in render, no thread-dependent branching). Divergence is detected and falls back to a full background render, losing the IFR benefit for that screen. - Side effects belong in lifecycle hooks (onMounted, watch callbacks) — these never run during the main-thread render. - Increases the main-thread bundle size (it now carries the Vue runtime). See https://lynxjs.org/guide/interaction/ifr | index.ts:286 |
includeWorkletPackages? | readonly (string | RegExp)[] | [] | Allowlist of bare-import specifiers whose 'main thread' worklets should be reached by the MT bundler. The worklet loader follows relative imports (./foo, ../bar) and resolves non-relative imports: path aliases and tsconfig paths that point at project source (outside node_modules) are followed automatically. Imports resolving INTO node_modules are dropped by default — list the package names (or RegExps matching them) here to follow worklets shipped as a published/installed package. Both checkpoints reduce their input to the package root before matching, so a pattern always matches the package name (e.g. '@my-org/foo'), never a subpath or the resolved filesystem path: - strings match the root exactly — '@vue-lynx/motion-mini' covers the package and all its subpath imports, but NOT '@vue-lynx/motion-mini-x'; - a RegExp like /^@my-org// matches whether the package is reached as an import or carved out of the node_modules loader exclude. Example pluginVueLynx({ includeWorkletPackages: ['@vue-lynx/motion-mini', /^@my-org/lynx-/], }) | index.ts:316 |
vapor? | boolean | false | Enable Vue Vapor mode support (experimental). Vapor mode is Vue's compilation-based, Virtual-DOM-free rendering mode, available since Vue 3.6 (currently in beta). Components opt in with the vapor attribute: <script setup vapor>. When enabled: - 'vue' is aliased to vue-lynx/vapor — the pure Vapor entry (shared runtime-core surface + Vapor helpers, no vdom renderer). - Vapor SFC templates compile through @vue/compiler-vapor in both dev (separate template compilation) and prod (inlined) builds. Pure Vapor apps and pure vdom apps are both supported; mixing vapor and vdom components in one app (vaporInteropPlugin) is not supported yet. | index.ts:336 |