Your first package vérifié avec le SDK 0.1.3

Ce guide crée un template React complet. Les variantes Vue et HTML/CSS/JS sont détaillées à l'étape 12. Chaque commande a été exécutée et vérifiée sur un projet neuf.

Avant de commencer

• Node.js 20.19+ (recommandé : 22 ou 24) et npm.
• Un terminal dans VS Code (menu Terminal → New Terminal).
• Un accès au panneau pour importer le résultat (Templates visuels).

Vérifiez votre version : node -v et npm -v.

1. Créer le projet

Le générateur crée le dossier, les fichiers et les scripts. Il n'installe rien encore.

npx @onirtech/create-onirtech-template mon-premier-template --stack react
cd mon-premier-template
npm install

Remplacez react par vue ou vanilla si besoin. Le nom doit être en minuscules, avec des tirets (mon-premier-template).

Le générateur affiche le nom de l'élément (onirtech-template-mon-premier-template) et les étapes suivantes.

2. Installer les dépendances

npm install installe React, Vite, Vitest et @onirtech/template-sdk.

npm install

Résultat attendu : found 0 vulnerabilities (ou des avertissements sans gravité).

3. Comprendre les fichiers

mon-premier-template/
├─ src/
│  ├─ index.js          enregistre le Custom Element (une ligne)
│  ├─ Aurora.jsx        votre interface (formulaire + chat)
│  ├─ styles.css        styles, inlinés dans le bundle
│  └─ manifest.ts       manifeste typé (id, version, params)
├─ tests/
│  └─ template.test.jsx tests unitaires (Vitest + happy-dom)
├─ harness/host.mjs     hôte simulé pour npm run dev
├─ tools/               validate, pack et orchestrateur dev
├─ vite.config.ts       build correct (SDK)
├─ package.json
└─ .gitignore

4. Lancer le projet en local

npm run dev

Ouvrez http://localhost:4500. Remplissez le formulaire (nom et email fictifs), puis discutez. Le harness simule l'hôte : aucune base, aucun réseau.

• ?phase=chat : démarre directement dans la discussion.
• ?consent=0 : lien sans consentement.
• ?titre=Mon%20titre : surcharge un paramètre.

Après une modification, le build se relance, mais la page ne se recharge pas toute seule : appuyez sur F5.

5. Lire l'entrée (une ligne)

Tout le squelette du Custom Element est géré par le SDK. Votre entrée ne fait qu'enregistrer le composant :

// src/index.js
import css from "./styles.css?inline";
import { defineReactTemplate } from "@onirtech/template-sdk/react";
import { Aurora } from "./Aurora";

defineReactTemplate("onirtech-template-mon-premier-template", Aurora, { css });

• css est une chaîne (import ?inline) injectée dans le Shadow DOM.
• Le nom doit être identique à ui.element dans le manifeste.

6. Déclarer un paramètre

Un paramètre est une variable réglable par lien, sans nouvelle version. Ajoutez couleur dans src/manifest.ts :

// src/manifest.ts
import { defineManifest } from "@onirtech/template-sdk";

export default defineManifest({
  id: "mon-premier-template",
  name: "Mon Premier Template",
  description: "Mon premier template ONIR CMS.",
  version: "1.0.0",
  publisher: { id: "onirtech", name: "ONIRTECH", trustLevel: "official" },
  ui: {
    mode: "web-component",
    entry: "./dist/index.js",
    element: "onirtech-template-mon-premier-template",
    shadowDom: "open",
  },
  capabilities: ["messages", "media", "theme"],
  params: [
    {
      key: "couleur",
      label: "Couleur d'accent",
      description: "Couleur des titres",
      type: "color",
      default: "#023777",
    },
    {
      key: "titre",
      label: "Titre",
      description: "Titre affiché en haut du formulaire et du chat",
      type: "string",
      default: "Discutons de votre projet",
      maxLength: 80,
    },
  ],
});

• default est obligatoire : c'est le repli.
• Types disponibles : string, text, number, boolean, color, url, select.
• Maximum 40 paramètres, 16 Ko de schéma.

7. Utiliser le paramètre dans l'interface

useTemplate() donne params, déjà résolu (valeurs du lien ou défauts). Modifiez src/Aurora.jsx :

// src/Aurora.jsx (extraits à modifier)
import { useState } from "react";
import { useTemplate } from "@onirtech/template-sdk/react";

export function Aurora() {
  const { phase, messages, params, actions } = useTemplate();
  const [draft, setDraft] = useState("");
  const accent = String(params.couleur ?? "#023777");

  // … formulaire d'identité …
  <h2 style={{ color: accent }}>
    {String(params.titre ?? "Discutons de votre projet")}
  </h2>

  // … dans la branche chat, même titre :
  <h2 style={{ color: accent }}>
    {String(params.titre ?? "Discutons de votre projet")}
  </h2>
}

Enregistrez puis rechargez http://localhost:4500/?couleur=%23c0392b : les titres passent en rouge. Sans paramètre, le défaut s'applique.

8. Ajouter un test

Ajoutez ce test dans tests/template.test.jsx (le fichier importe déjà l'entrée) :

// tests/template.test.jsx
import { expect, it } from "vitest";
import { createMockContext, mountTemplate } from "@onirtech/template-sdk/testing";
import "../src/index.js";

it("affiche le titre fourni par le lien", () => {
  const ctx = createMockContext({ params: { titre: "Album souvenirs" } });
  const { el } = mountTemplate("onirtech-template-mon-premier-template", ctx);

  expect(el.shadowRoot.textContent).toContain("Album souvenirs");
});

npm test

Attendu : Test Files 1 passed. Les helpers montent le vrai élément et poussent un contexte complet.

9. Construire le bundle

npm run build

Le build produit deux fichiers :

• dist/index.js — le template (React inclus) ;
• onirtech.template.json — le manifeste final, avec ui.entry et l'intégrité SRI.

Ne modifiez pas onirtech.template.json à la main : il est régénéré à chaque build.

10. Valider et empaqueter

npm run validate
npm run pack

validate vérifie le manifeste, l'entrée, l'élément et l'intégrité. pack crée l'archive :

release/mon-premier-template-1.0.0.onirtech-template

L'archive contient le bundle, le manifeste et le fichier de release (sha256). C'est elle que vous importez.

11. Importer et rattacher à un lien

1. Panneau → Templates visuels → Importer → choisir l'archive.
2. Ouvrir le lien concerné → choisir le template et sa version.
3. Renseigner les paramètres (titre, couleur), puis Aperçu avec ces valeurs.
4. Enregistrer, puis ouvrir le lien public.

Une version importée est immuable : pour corriger, publiez une nouvelle version (étape 12).

12. Publier une mise à jour (et variantes)

Changez version dans src/manifest.ts (c'est la source de vérité, pas package.json), puis :

npm run build
npm run validate
npm run pack

Réimportez l'archive 1.1.0 et sélectionnez la nouvelle version sur le lien. L'ancienne reste intacte.

Variante vanilla (HTML/CSS/JS, sans build)

--stack vanilla : les styles sont dans src/styles.js (constante CSS) et le manifeste est un JSON. L'entrée utilise defineTemplate :

// src/index.js — stack vanilla (aucun build)
import { defineTemplate, h, param } from "@onirtech/template-sdk";

defineTemplate(
  "onirtech-template-mon-premier-template",
  (ctx) =>
    h("h2", {
      text: param(ctx, "titre", "Discutons de votre projet"),
    }),
  { css: ":host { display: block; font-family: system-ui, sans-serif; }" },
);

Scripts : npm run dev, npm test, npm run validate, npm run pack — pas de build.

Variante Vue

--stack vue : le composant est un SFC et le composable remplace le hook.

<!-- src/Aurora.vue (extrait) -->
<script setup>
import { useTemplate } from "@onirtech/template-sdk/vue";

const { phase, messages, params, actions } = useTemplate();
</script>

<template>
  <h2>{{ params.titre }}</h2>
  <!-- … -->
</template>

Build et scripts identiques à React. L'entrée utilise defineVueTemplate (généré).

Récapitulatif

Dépannage

npm run build échoue : « Cannot find module 'react' ».

Lancez npm install dans le projet (les dépendances ne sont pas installées).

Erreur navigateur « process is not defined » (écran blanc).

Ancien SDK : mettez à jour avec npm install @onirtech/template-sdk@latest (0.1.3+), puis npm run build. Le build définit désormais process.env.NODE_ENV.

Erreur Vite « transformWithEsbuild » ou « esbuild ».

Mettez à jour le SDK : npm install @onirtech/template-sdk@latest (0.1.2+ utilise transformWithOxc).

L'élément ne s'affiche pas dans le harness.

Vérifiez que ui.element dans le manifeste est exactement le nom passé à defineReactTemplate / defineTemplate.

Les styles ne s'appliquent pas.

Importez le CSS en ?inline et passez-le à l'option css.

params.couleur est undefined.

Le paramètre n'est pas déclaré dans params, ou le harness n'a pas de valeur : gardez un repli (?? "#023777").

« Invalid hook call ».

Deux copies de React sont chargées : supprimez node_modules et relancez npm install.

Référence complète de l'API : documentation du SDK. Contrat des templates : templates visuels. Traitement des messages : les actions d'un template.