Assets — JS, SCSS & React

Elementum intègre un pipeline de compilation moderne basé sur Vite. Chaque thème ou plugin dispose de sa propre configuration vite.config.js et d'une structure assets/ standardisée.

Structure

assets/
  index.ts          ← bundle front (AlpineJS + React + JS)
  admin.ts          ← bundle admin (AlpineJS + React admin)
  customize.ts      ← bundle Customizer (champs React)
  js/
    app.ts          ← point d'entrée JS métier (utils, helpers…)
    interfaces/     ← types TypeScript (ElementumObject, etc.)
    utils/          ← utilitaires (passwordReveal, etc.)
  scss/
    main.scss       ← styles front principal
    admin.scss      ← styles administration
    customize.scss  ← styles Customizer
    utils/          ← variables, breakpoints
    components/     ← composants SCSS réutilisables
    layouts/        ← header, footer…
  src/
    Hooks/          ← utilitaires JS partagés (mountReactComponent…)
    Components/     ← composants React front
    CustomizeFields/← champs React du Customizer

Compilation

# Développement (watch)
npm run dev

# Production
npm run build

Les fichiers compilés sont générés dans assets/dist/ :

Fichier de sortie	Source	Contexte
bundle.js	assets/index.ts	Front
bundleAdmin.js	assets/admin.ts	Admin WordPress
bundleCustomize.js	assets/customize.ts	Customizer WordPress
css/styles.css	assets/scss/main.scss	Front
css/stylesAdmin.css	assets/scss/admin.scss	Admin
css/stylesCustomize.css	assets/scss/customize.scss	Customizer

Les bundles TypeScript

index.ts — Bundle front

Point d'entrée principal du front. Il démarre AlpineJS et importe le code métier :

assets/index.ts

import Alpine from "alpinejs";
import { mountReactComponent } from "./src/Hooks/mountReactComponent";

window.Alpine = Alpine;
Alpine.start();

// Vos composants React front
// mountReactComponent(".mon-composant", MonComposant);

import("./js/app.ts");

admin.ts — Bundle admin

Même structure que index.ts, dédié aux pages d'administration WordPress.

customize.ts — Bundle Customizer

Réservé aux champs React du Customizer. Les champs color_contrast et remix_icon fournis par Elementum y sont montés automatiquement :

assets/customize.ts

import { mountReactComponent } from "./src/Hooks/mountReactComponent";

// Champs personnalisés fournis par Elementum
import ColorContrast from "./src/CustomizeFields/ColorContrast/main";
import RemixIconSelect from "./src/CustomizeFields/RemixIconSelect/main";

mountReactComponent(".color-contrast-checker", ColorContrast);
mountReactComponent(".remix-icon-select", RemixIconSelect);

AlpineJS

AlpineJS est disponible dès le démarrage dans les trois bundles. Il suffit d'utiliser les directives x-data, x-bind, x-on, etc. directement dans les templates Twig :

<div x-data="{ open: false }">
    <button @click="open = !open">Toggle</button>
    <p x-show="open">Contenu visible</p>
</div>

Pas de configuration supplémentaire requise.

Composants React — mountReactComponent

mountReactComponent est l'utilitaire central pour monter un composant React sur un ou plusieurs éléments DOM identifiés par un sélecteur CSS.

mountReactComponent(selector: string, Component: React.FC): void

Comportement :

• Monte le composant sur chaque élément correspondant au sélecteur
• Transmet automatiquement les attributs data-* de l'élément en props du composant
• Fonctionne dans tous les contextes : front, admin, Customizer
• Supporte les éléments ajoutés dynamiquement (via MutationObserver)
• Se re-déclenche sur l'événement ready du Customizer WordPress

Exemple

Côté PHP/Twig, on pose un conteneur avec des données en data-* :

<div class="mon-composant"
     data-title="Bonjour"
     data-count="42">
</div>

Côté TypeScript dans index.ts :

import MonComposant from "./src/Components/MonComposant/main";
import { mountReactComponent } from "./src/Hooks/mountReactComponent";

mountReactComponent(".mon-composant", MonComposant);

Le composant React reçoit { title: "Bonjour", count: "42" } en props (toutes les valeurs sont des string car issues de dataset).

assets/src/Components/MonComposant/main.tsx

export default function MonComposant({
    title,
    count,
}: {
    title: string;
    count: string;
}) {
    return (
        <div>
            <h2>{title}</h2>
            <span>{count}</span>
        </div>
    );
}

React optionnel

React n'est pas activé par défaut dans le boilerplate. Pour l'activer, décommentez react() dans vite.config.js et installez les dépendances :

npm install react react-dom
npm install -D @vitejs/plugin-react

SCSS

Structure recommandée

assets/scss/
  main.scss          ← importe tout
  utils/
    _variables.scss  ← variables CSS/SCSS ($colors, $fonts…)
    _breakpoints.scss← mixins responsive
  layouts/
    _header.scss
    _footer.scss
  components/
    _button.scss
    _card.scss
  pages/
    _home.scss

Alias @elementum

Le vite.config.js expose un alias @elementum pointant vers les assets du plugin Elementum. Vous pouvez ainsi importer les variables et utilitaires Elementum directement :

@import "@elementum/scss/utils/variables";
// Donne accès à $elementum-primary, $elementum-font, etc.

Variables Customizer dans SCSS

Les valeurs du Customizer sont injectées automatiquement comme propriétés CSS. Dans vos styles, utilisez-les via var() :

.hero {
    background-color: var(--color-primary);
    color: var(--color-text);
}

window.ELEMENTUM

Le plugin Elementum expose un objet global window.ELEMENTUM (localisé via wp_localize_script) contenant les informations du contexte courant :

interface ElementumObject {
    main: { url: string; slug: string; path: string };
    theme: { url: string; slug: string; path: string };
    child: { url: string; slug: string; path: string };
    // …et toutes les clés ajoutées via le filtre elementum.localize
}

Il est disponible dans app.ts et dans tout composant importé depuis ce fichier.

Pour ajouter des données côté PHP :

add_filter('elementum.localize', function (array $data): array {
    $data['mon_plugin'] = ['version' => '1.0.0'];
    return $data;
});

Alias Vite

Alias	Résout vers
@	assets/ (thème courant)
@elementum	wp-content/plugins/elementum/assets/