Experimentals Reference

このページは Experimentals と Vue RFC Experimental Details の dense reference です。どの entry point が flag を解決するか、変更に必要な proof は何か、どの low-level API field がすでに final boolean なのかを確認するときに使います。

Entry Points

その判断を所有している最も高レベルの entry point を使ってください。project config は Vize config を読むツール向け、direct plugin option は 1 つの Vite plugin instance 向け、native compiler field は project policy をすでに解決した integration 向けです。

Flag Contracts

RFC #831 も他の RFC flag と同じ opt-in shape です。ただし挙動は parser/tooling-only で、attribute 近くの // annotation を保持し、runtime comment は emit しません。

Direct API Fields

ほとんどの application は experimentals を設定します。config resolution を自前で済ませる低レベル integration だけが native compiler field を直接渡してください。

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,
});

これらの field は解決済み boolean です。alias、{} switch object、shared-config precedence は解釈しません。caller がその解決ルールを所有する integration boundary でだけ使います。

Config Recipes

意図した behavior を証明する最小の flag set だけを有効にします。無関係な RFC switch を 1 つの project toggle にまとめないでください。また、feature が stable な compiler option または tool option に移るまでは、experimental flag を shared config で default-on に昇格しません。

shared config で 1 つの RFC proposal だけを有効にする例:

import { defineConfig } from "vize";

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

shared config は有効のまま、一時的に plugin instance だけ opt-out する例:

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

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

config resolution 後の低レベル integration:

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

native API call には intagComment のような compatibility alias や {} のような switch object を 渡しません。compiler を呼ぶ前に解決してください。

Failure Examples

patternedTemplate は構造が違うと fail-closed です。

<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 は attribute 用の第 2 の expression grammar ではありません。

<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 shape は TypeScript cardinality contract として保持します。

Implementation Coverage

Release Safety Checklist

release note で experimental surface を claim する前に、shipped entry point に対して以下を確認します。

• public config key と direct native field の default-off behavior が検証されている
• alias は recommended name ではなく compatibility input として記載されている
• direct Vite plugin value が shared config を有効化でき、かつ明示的に opt-out できる
• false、null、true、{} が documented switch semantics を維持する
• vapor や jsxVapor のような backend fallback flag は stable compiler option より弱い
• RFC example には enabled example と flag-off または invalid-shape diagnostic example の両方がある
• boundary が patterned-template editor navigation や dynamic component に対する strict slot support などの deferred behavior を明記している