Experimentals Reference

This page is the dense reference for Experimentals and Vue RFC Experimental Details. Use it when you need to know which entry point resolves a flag, what proof belongs with a change, and which low-level API fields are already final booleans.

Entry Points

Use the highest-level entry point that still owns the decision. Project config is for tools that load Vize config, direct plugin options are for one Vite plugin instance, and native compiler fields are only for integrations that have already resolved project policy.

Flag Contracts

RFC #831 has the same opt-in shape as the other RFC flags, but its behavior is parser/tooling-only: it keeps // annotations near attributes and does not emit runtime comments.

Direct API Fields

Most applications should configure experimentals. Lower-level integrations that already perform their own config resolution can pass native compiler fields directly:

import {
  compile,
  compileSfc,
  compileSfcBatchWithResults,
  compileVapor,
  parseTemplate,
} from "@vizejs/native";

compile(templateSource, {
  experimentalInTagComments: true,
  experimentalPatternedTemplate: true,
  experimentalSelfComponent: true,
  experimentalServerScript: true,
  componentName: "TreeNode",
});

compileVapor(templateSource, {
  experimentalInTagComments: true,
  experimentalPatternedTemplate: true,
  experimentalSelfComponent: true,
  componentName: "TreeNode",
});

parseTemplate(templateSource, {
  experimentalInTagComments: true,
});

compileSfc(sfcSource, {
  filename: "TreeNode.vue",
  experimentalInTagComments: true,
  experimentalPatternedTemplate: true,
  experimentalSelfComponent: true,
  experimentalStrictSlotChildren: true,
  experimentalServerScript: true,
});

compileSfcBatchWithResults(files, {
  experimentalInTagComments: true,
  experimentalPatternedTemplate: true,
  experimentalSelfComponent: true,
  experimentalStrictSlotChildren: true,
  experimentalServerScript: true,
});

These fields are already resolved booleans. They do not understand aliases, {} switch objects, or shared-config precedence. Use them only at integration boundaries where the caller owns those rules.

Config Recipes

Enable the smallest flag set that proves the intended behavior. Do not group unrelated RFC switches behind one project toggle, and do not promote an experimental flag to default-on in shared config until the feature has moved to a stable compiler or tool option.

One RFC proposal in shared config:

import { defineConfig } from "vize";

export default defineConfig({
  experimentals: {
    inTagComment: true,
  },
});

Temporary per-plugin opt-out while shared config stays enabled:

import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [
    vize({
      experimentals: {
        inTagComment: false,
        patternedTemplate: null,
      },
    }),
  ],
});

Low-level integration after config resolution:

compile(templateSource, {
  experimentalInTagComments: resolvedExperimentals.inTagComments,
  experimentalPatternedTemplate: resolvedExperimentals.patternedTemplate,
});

In native API calls, never pass compatibility aliases such as intagComment or switch objects such as {}. Resolve them before calling the compiler.

Failure Examples

patternedTemplate stays fail-closed when structure is wrong:

<template v-match="status"></template>

<template v-match="status">
  <p v-when:ready="'ready'">Ready</p>
  <p v-when.once="'ready'">Ready again</p>
</template>

inTagComment is not a second expression grammar for attributes:

<template>
  <LegacySelect :label="'// this is an attribute value, not an in-tag comment'" />

  <LegacySelect
    :// not a directive argument comment
    selected-id="abc"
  />
</template>

Slot Cardinality

RFC #734 return shapes are preserved as TypeScript cardinality contracts:

Implementation Coverage

Release Safety Checklist

Before release notes claim an experimental surface, check all of these against the shipped entry point:

• default-off behavior is verified for the public config key and the direct native field
• aliases are documented as compatibility inputs, not as recommended names
• direct Vite plugin values can enable and explicitly opt out of shared config
• false, null, true, and {} keep the documented switch semantics
• backend fallback flags such as vapor and jsxVapor lose to stable compiler options
• RFC examples include both an enabled example and a flag-off or invalid-shape diagnostic example
• boundaries name deferred behavior, such as patterned-template editor navigation or strict slot support for dynamic components