Routine d'initialisation d'un projet

📋 À propos
Cette routine constitue une base commune à toutes nos typologies de projets (statique, Nuxt, WordPress). Elle standardise l’environnement, les outils de qualité, la structure CSS et les options liées.

Sommaire

💡 Important :

  • Dans la majorité des projets “simples”, l’étape 2 (fichiers de configuration) n’est pas nécessaire car Vite génère l’essentiel.
  • Cas des projets “multi” (mono-repo) avec une partie front (Vite) et d’autres parties au sein du même dépôt: réaliser l’étape 2 (fichiers de configuration) avant l’étape 1 (Vite).

Stack commune à tous les projets

Environnement / compilation

  • pnpm : gestionnaire de paquets
  • Vite : bundler/outil de compilation

Linters / qualité

  • Editorconfig : indentation, encodage, EOL
  • Prettier : formatage automatique
  • Stylelint : vérification CSS
  • ESLint : vérification JavaScript/TypeScript (+ frameworks)

CSS

  • Tailwind : nous intégrons nos projets en CSS Vanilla avec Tailwind disponible pour les cas d'usage spécifiques.

📚 La plupart des fichiers de configuration sont disponibles dans configs/.

1. Vite

1) Se placer à la racine et créer un projet

pnpm create vite
# choisir le nom du projet
# sélectionner "Vanilla + JavaScript" (ou "TypeScript")
cd <vite-project>
pnpm install

2) Ajouter la configuration Vite

3) Nettoyer les fichiers d’exemple

  • Supprimer: counter.js, javascript.svg, public/vite.svg
  • Renommer style.css en styles.css
  • Nettoyer main.js pour ne conserver que l’import CSS
  • Dans index.html: définir lang="fr", ajuster <title>, supprimer le favicon <link rel="icon">

4) Utiliser le dossier public/ pour les assets statiques

Tâches Vite

pnpm dev    # démarrer le serveur de développement
pnpm build  # compiler la version de production (dossier dist/)

2. Fichiers de configuration

Note: la plupart sont générés automatiquement par Vite. Vérifier leur présence.

1) Pré-requis

# installer pnpm s'il n'est pas présent
npm install -g pnpm
# créer un dossier racine si besoin
mkdir projet && cd projet
# initialiser le package
pnpm init

2) Fichiers racine

3) Dossier VS Code

3. Linter, formatters et correcteurs

On installe les linters après avoir choisi le type de projet (vanilla, Vue/Nuxt, WordPress).

1) ESLint (JS/TS)

pnpm create @eslint/config@latest

2) Prettier (formatteur)

pnpm install --save-dev prettier
  • Extension VS Code: “Prettier - Code formatter”
  • Ajouter .prettierrc.mjs à la racine

3) Stylelint (CSS)

pnpm install --save-dev stylelint stylelint-config-standard stylelint-config-html stylelint-order stylelint-config-property-sort-order-smacss
  • Extension VS Code: “Stylelint”
  • Ajouter stylelint.config.js à la racine
  • Dans VS Code (cmd+,), ajouter:
"stylelint.validate": ["css", "scss", "html", "vue"]

💡 Important : Relancer VS Code pour activer les linters: cmd+maj+p → “Reload Window”

4. Styles CSS

Tailwind

Tailwind CSS n'est pas inclus systématiquement mais est conseillé, même en projet “vanilla”, pour disposer au besoin de classes utilitaires.

app.css

Le fichier app.css (ou app.css pour la variante Tailwind) est le point d’entrée. Il charge les feuilles dans l’ordre des layers CSS: config, base, components, utilities.

1) Layer config (reset, polices, thèmes, layouts)

  • reset.css: reset moderne + print
  • theme.css: primitives (ex. --color-pink-500: #f1498f) issues de Figma
    Voir “Primitives” dans les Guidelines CSS
  • theme-tokens.css: design tokens (ex. --primary: --color-pink-500;)
    Voir “Tokens (=roles)” dans les Guidelines CSS
  • layouts.css: utilitaires de disposition (Bretzel)
  • natives.css: styles natifs des éléments HTML

2) Layer base

  • styles.css: styles globaux du projet (gabarits, typo, liens, etc.)

3) Layer components

  • Feuilles de styles des composants

4) Layer utilities

  • Tailwind et/ou utilitaires personnalisés

📚 Outil : Primary est un configurateur CSS pour les projets Alsacréations. Il permet de générer des fichiers CSS conformes aux normes de l'équipe.

5. Custom Media Queries (optionnel)

Installer le plugin PostCSS Custom Media:

pnpm add -D postcss-custom-media

Ajouter postcss.config.mjs:

export default {
  plugins: {
    "postcss-custom-media": {
      /* plugin options */
    },
  },
}

Déclarer les breakpoints du projet:

/* assets/css/theme.css */
@custom-media --md (width >= 48rem); /* 768px */
@custom-media --lg (width >= 64rem); /* 1024px */
@custom-media --xl (width >= 80rem); /* 1280px */
@custom-media --xxl (width >= 96rem); /* 1536px */

Utilisation dans les règles (syntaxe moderne des plages):

.toc {
  padding: var(--spacing-s);
  border-radius: var(--radius-md);

  @media (--lg) {
    position: fixed;
    top: var(--spacing-m);
    left: var(--spacing-s);
  }
}

Remplacement effectué à la compilation:

@media (--md) { /* … */ }
/* devient */
@media (width >= 48rem) { /* … */ }

Avantages

  • Centralisation des seuils (un seul fichier)
  • Lisibilité (noms explicites --md, --lg, --xl)
  • Cohérence (mêmes breakpoints partout)

6. Autres Options (selon projets)

  • Sass
pnpm install --save-dev sass
# renommer styles.css -> styles.scss
# adapter l'import dans main.js
  • Alpine.js
pnpm install --save alpinejs
  • Docker (recette / pré-production)
    • Ajouter Dockerfile et docker-compose.yml depuis les exemples et les adapter
    • Mise en production (optionnel): docker-compose up -d --build