Aller au contenu
Vincle

Chargement…

    Transformation de précompilation

    La précompilation transforme les parties statiques du JSX en modèles HTML tout en conservant les contrôles des valeurs dynamiques.

    // Before: runtime creates a VNode tree
    jsx("div", { class: cls }, jsx("span", {}, text));
    

    // After (precompile): direct string assembly
    jsxTemplate`<div ${jsxAttr("class", cls)}><span>${jsxEscape(text)}</span></div>`;

    Code produit#

    Le build produit des appels au runtime de templates et des segments HTML préassemblés. Les expressions dynamiques passent par les fonctions de sérialisation adaptées.

    Bénéfices#

    Le moteur évite de reconstruire et de parcourir les sous-arbres statiques à chaque requête. Le gain dépend de la proportion de HTML statique et des données de votre page.

    Installation#

    Installez @vincle/precompile avec Bun, pnpm ou npm. Le transform utilise Core pour le rendu et ses fonctions de sécurité.

    Fenêtre de terminal
    npm install -D @vincle/precompile

    Utilisation#

    Vous pouvez intégrer le transform à Vite, Bun ou votre propre pipeline. Il doit traiter les fichiers utilisant le runtime JSX Vincle.

    Vite#

    Ajoutez le plugin de précompilation à la configuration Vite. Définissez aussi jsxImportSource pour les fichiers JSX concernés.

    import precompile from "@vincle/precompile/vite";
    import { defineConfig } from "vite";
    

    export default defineConfig({
      plugins: [precompile()],
    });

    Bun#

    Branchez le plugin Bun dans votre build ou votre configuration de compilation.

    preload.ts
    import { plugin } from "bun";
    import precompile from "@vincle/precompile/bun";
    

    plugin(precompile());
    Fenêtre de terminal
    bun --preload ./preload.ts server.ts

    Autres pipelines#

    Appelez le transform directement dans un autre pipeline et transmettez le code transformé ainsi que sa source map à l’étape suivante.

    import precompileTransform from "@vincle/precompile";
    

    const result = precompileTransform(code, "/src/App.tsx", {
      runtimeSource: "@vincle/core/jsx-runtime",
    });
    // → { code, map } | null: null when there was nothing to rewrite

    Vérifier que la transformation est active#

    Inspectez la sortie compilée pour vérifier les imports du runtime et les modèles générés. Une simple configuration JSX ne prouve pas que la précompilation est active.

    [vincle/precompile] nothing was precompiled in this build: no
    .jsx/.tsx module passed through it at all (11 module(s) seen). …

    Runtime personnalisé#

    Un runtime personnalisé doit respecter le contrat des fonctions importées par le transform. Conservez les garanties de sérialisation des attributs et du contenu.

    precompile({
      runtimeSource: "custom/jsx-runtime",
    });
    vincle-runtime.ts
    export * from "@vincle/core/jsx-precompile-runtime";

    Assainissement pendant le build#

    Les parties statiques sont assainies au build. Les valeurs dynamiques restent contrôlées à l’exécution. Les animations SVG dont la sécurité dépend de l’élément complet reviennent au runtime ; la précompilation ne rend pas un appel raw() sûr.

    // Static string: looks harmless, linter passes
    <a href="javascript:alert(1)">click</a>
    

    // Targeting @vincle/core → blocked at build time
    //   <a href="#blocked">click</a>
    

    // Targeting another runtime → inlined verbatim in the bundle
    //   <a href="javascript:alert(1)">click</a>