Pipelines CSS (SCSS vs Tailwind)

Flexweg CMS supporte deux workflows CSS pour les thèmes — choisis par thème selon les fichiers présents :

• Pipeline SCSS : theme.scss existe, pas de tailwind.config.cjs. Vite compile le SCSS au build. Utilisé par le thème default.
• Pipeline Tailwind : theme.css + tailwind.config.cjs existent les deux. Un étape de prebuild lance le Tailwind CLI avant Vite. Utilisé par magazine et corporate.

Un seul est actif par thème. Vous pouvez mélanger les deux entre thèmes dans le même admin (le script de build auto-détecte).

Pipeline SCSS

Quand l'utiliser

• Vous êtes à l'aise avec SCSS (variables, nesting, mixins).
• Vous voulez écrire une CSS toute petite, sans tooling JIT.
• Le thème default est votre référence — clonez-le si vous voulez démarrer du SCSS.

Comment

src/themes/<id>/theme.scss contient toute la CSS. Le manifest l'importe :

// manifest.ts
import cssText from "./theme.scss?inline";

const manifest: ThemeManifest = {
  cssText,
  // ...
};

?inline est un suffixe Vite qui compile le SCSS au build et expose le résultat en string.

Workflow

npm run build    # compile thème + tout le reste, output dist/admin/ + dist/theme-assets/

Pendant le dev, npm run dev recompile à chaque save de theme.scss (HMR).

Astuce

Pour un thème customisable, utilisez des variables CSS au lieu de variables SCSS, et exposez-les via compileCss(config) :

:root {
  --color-primary: #3366ff;
  --color-text: #1a1a1a;
  --font-headline: 'Inter', sans-serif;
}

Dans compileCss, ajoutez un :root { ... } à la fin avec les overrides utilisateur. Voir le style.ts du thème default.

Pipeline Tailwind

Quand l'utiliser

• Vous êtes à l'aise avec Tailwind (utility classes, JIT).
• Vous voulez profiter du purge auto (la CSS ne contient que les classes utilisées).
• Magazine / corporate / marketplace-core sont vos références.

Comment

src/themes/<id>/theme.css contient les directives Tailwind :

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .mp-card { @apply rounded-lg p-4 shadow-sm; }
}

src/themes/<id>/tailwind.config.cjs configure le scan + thème :

module.exports = {
  content: ["./src/themes/marketplace-core/**/*.{ts,tsx,html,js}"],
  // CRITIQUE : inclure les .js pour les loaders runtime
  theme: {
    extend: {
      colors: {
        primary: "rgb(var(--color-primary) / <alpha-value>)",
      },
    },
  },
};

Critique : le content glob doit inclure .js si votre thème ship des loaders runtime (menu-loader.js, posts-loader.js) qui contribuent à des classes Tailwind. Sinon le purge JIT les vire.

Le pré-build

scripts/build-theme-tailwind.mjs tourne avant Vite (wired into prebuild + predev dans package.json). Pour chaque thème avec un tailwind.config.cjs, il invoque le CLI Tailwind sur theme.css et écrit theme.compiled.css.

# Pour itérer en dev :
npx tailwindcss -c src/themes/marketplace-core/tailwind.config.cjs \
  -i src/themes/marketplace-core/theme.css \
  -o src/themes/marketplace-core/theme.compiled.css \
  --watch

Dans un autre terminal npm run dev pour le hot-reload Vite. La CSS recompilée à chaque save est picked-up par Vite via le ?inline du manifest.

Le manifest

import cssText from "./theme.compiled.css?inline";

const manifest: ThemeManifest = {
  cssText,
  // ...
};

Le scoping

Le content du tailwind.config.cjs est scopé au dossier du thème uniquement. Cela évite que les utility classes de l'admin SPA bundle ne fuient dans le CSS du thème.

Material 3 et variables RGB

Magazine et corporate utilisent le système Material 3 avec des variables RGB triplets :

:root {
  --color-primary: 0 0 0;  /* black */
}

// tailwind.config.cjs
theme: {
  extend: {
    colors: {
      primary: "rgb(var(--color-primary) / <alpha-value>)",
    },
  },
},

Cela permet d'utiliser bg-primary/50 (alpha) sans hacks. Si votre compileCss accepte des hex de l'utilisateur, convertissez-les en triplets RGB au moment de l'injection.

compileCss au-dessus des deux pipelines

compileCss(config) opère sur cssText (qui est déjà compilé peu importe le pipeline). Vous pouvez :

• Append un :root { ... } avec les overrides utilisateur
• Swap un @import url(...) de Google Fonts
• Insérer des --var supplémentaires en fin de fichier

Voir le style.ts du default ou du magazine pour des exemples complets.

Anti-patterns

• Ne pas servir une grosse base CSS framework (Bootstrap, Foundation) en plus de Tailwind — coût lourd pour rien
• Ne pas charger des fonts depuis le HTML inline (<link> dans BaseLayout) sauf preconnect. Mettez-les dans la CSS (@import url(...)) — comme ça les changements de fonts se font sans rebuild HTML.
• Ne pas oublier .js dans le content de Tailwind si votre thème ship des loaders runtime. Sans ça les classes JIT-purgées disparaissent.