---
title: "Transformation de précompilation"
headingIds:
  [
    "precompile-transform",
    "what-it-outputs",
    "what-it-buys",
    "install",
    "usage",
    "vite",
    "bun",
    "any-other-pipeline",
    "knowing-it-runs",
    "custom-runtime",
    "build-time-sanitization",
  ]
---

# 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.

```ts
// 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é.

```bash tab="npm" sync="pkg-manager"
npm install -D @vincle/precompile
```

```bash tab="pnpm" sync="pkg-manager"
pnpm add -D @vincle/precompile
```

```bash tab="bun" sync="pkg-manager"
bun add -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.

```ts
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.

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

plugin(precompile());
```

```bash
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.

```ts
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.

```ts
precompile({
  runtimeSource: "custom/jsx-runtime",
});
```

```ts
// 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.

```ts
// 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>
```