Structure des répertoires - rocambille/start-express-react GitHub Wiki

Introduction

La structure par défaut d'une application StartER est un point de départ. Vous êtes libre d'organiser votre application comme bon vous semble. StartER n'impose aucune contrainte quant à l'emplacement d'un élément, tant que vous adaptez le code à votre organisation : vous avez la main !

.
├── .env
├── .env.sample
├── compose.yaml
├── compose.prod.yaml
├── Dockerfile
├── index.html
├── server.ts
└── src
    ├── database
    │   └── schema.sql
    ├── express
    │   ├── routes.ts
    │   └── modules
    │       └── ...
    ├── react
    │   ├── routes.tsx
    │   ├── components
    │   │   └── ...
    │   └── pages
    │       └── ...
    └── types
        └── index.d.ts

Le répertoire racine

Les fichiers .env

StartER utilise un fichier .env pour séparer les variables d'environnement du code. Lors d'une nouvelle installation de StartER, le répertoire racine de votre application contiendra un fichier .env.sample qui définit les variables d'environnement courantes. Après l'installation de StartER, copiez ce fichier .env.sample sous le nom .env.

cp .env.sample .env

Voici les variables obligatoires que vous devez renseigner avec vos propres valeurs :

Variable Description
APP_SECRET Clé secrète utilisée pour générer la signature pour l'authentification
MYSQL_ROOT_PASSWORD Mot de passe du compte superutilisateur root MySQL
MYSQL_DATABASE Nom de la base de données de votre application

L'image Docker mysql permet des variables supplémentaires comme MYSQL_USER, MYSQL_PASSWORD ou MYSQL_RANDOM_ROOT_PASSWORD. Référez-vous à la documentation de l'image mysql pour plus de détails.

Également dans votre fichier .env, vous pouvez ajouter :

  • des variables supplémentaires pour des outils tiers que vous avez installés,
  • vos propres variables.

À retenir

  • Vous pouvez inclure des variables supplémentaires dans le fichier .env.sample de votre application. En ajoutant des entrées dans le fichier .env.sample, les autres développeurs de votre équipe peuvent clairement identifier les variables d'environnement nécessaires à l'exécution de votre application.

  • Votre fichier .env ne doit jamais être ajouté dans un commit avec Git, car chaque poste (machine locale ou serveur) exécutant votre application pourrait avoir besoin d'une configuration d'environnement différente. De plus, cela constituerait un risque de sécurité si des intrus accédaient à votre dépôt, car vos identifiants sensibles seraient exposés.

Pour démarrer votre application, StartER utilise tsx (qui utilise la commande node sous le capot) avec l'option --env-file pour charger votre fichier .env. Vos variables sont alors disponibles sur process.env.

// Get variables from .env file for database connection
const { MYSQL_ROOT_PASSWORD, MYSQL_DATABASE } = process.env;

Vous pouvez éditer les options de la commande tsx dans les scripts du fichier package.json à la racine du projet.

{
  "scripts": {
    "dev": "tsx --env-file=.env server",
    "start": "tsx --env-file=.env server",
    ...
  },
  ...
}

Par exemple, vous pouvez passer plusieurs arguments --env-file pour construire une configuration plus complexe avec des fichiers .env multiples (.env.local, .env.prod...). Référez-vous à la documentation de --env-file pour plus de détails.

Les fichiers Docker

D'après la documentation officielle :

Docker permet de packager et d'exécuter une application dans un environnement isolé appelé conteneur.
[...] Un conteneur est une instance exécutable d'une image.
[...] Docker peut créer des images automatiquement en lisant les instructions d'un fichier Dockerfile.

Un fichier Dockerfile définit le contenu et le comportement au démarrage d'un conteneur unique. L'image d'une application StartER est basée sur une image d'Alpine Linux avec la dernière version LTS de Node.js pré-installée.

ARG NODE_VERSION=22.14.0

FROM node:${NODE_VERSION}-alpine

Le fichier Dockerfile copie les sources de votre application dans cette image, installe les dépendances et lance la commande npm run dev.

COPY . .

# Run the application.
CMD ["npm", "run", "dev"]

Notez que le fichier .dockerignore permet d'ignorer les fichiers non pertinents pour la copie dans l'image (README, LICENSE...).

En complément, un fichier compose.yaml permet de définir une application multi-conteneurs. Dans un réseau isolé, le fichier compose.yaml de StartER définit :

  • un conteneur server pour votre application,
  • un conteneur database pour fournir un serveur MySQL à votre application,
  • un conteneur adminer pour fournir une interface graphique de gestion de base de données avec Adminer.

Pour démarrer l'application en mode développement, lancez la commande :

docker compose up --build

Des options supplémentaires sont disponibles dans la documentation de docker compose up.

Le fichier compose.prod.yaml spécialise votre application pour la production :

  • La variable d'environnement NODE_ENV est définie avec la valeur production.
  • Le conteneur server est lancé avec la commande npm run build && npm run start plutôt que npm run dev.
  • Le conteneur adminer n'est pas fourni.

Pour démarrer l'application en mode production, lancez la commande :

docker compose -f compose.prod.yaml up --build

Le fichier index.html

Le fichier index.html référence entry-client et inclut un marqueur <!--ssr-outlet--> où le balisage rendu par le serveur est injecté (voir les explications sur le serveur unique de StartER pour les détails avancées).

Également, le fichier index.html est le point d'ancrage pour Pico CSS en liant la bibliothèque et en ajustant des premierères variables.

<!DOCTYPE html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Start Express React</title>
    <link
      rel="shortcut icon"
      href="/src/react/assets/images/favicon.png"
      type="image/png"
    />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css"
    />
    <style>
      :root {
        --pico-border-radius: 2rem;
        --pico-form-element-spacing-vertical: 0.5rem;
        --pico-form-element-spacing-horizontal: 1rem;
      }
    </style>
  </head>
  <body>
    <div class="container" id="root"><!--ssr-outlet--></div>
    <script type="module" src="/src/entry-client"></script>
  </body>
</html>

Référez-vous à la documentation de Pico CSS pour la liste des variables disponibles.

Le fichier server.ts

Le fichier server.ts est le point d'entrée du framework. Son code fait la liaison entre votre application Express et un serveur Vite pour créer un serveur unique.

Le répertoire src

La majeure partie de votre application est hébergée dans le répertoire src. Par défaut, le répertoire src contient les répertoires :

  • database,
  • express,
  • react,
  • types.

Les répertoires express et react sont expliqués plus en détail dans leurs pages respectives, mais considérez-les comme le cœur de votre application. Le répertoire express contient toutes vos routes backend, tandis que le répertoire react contient toutes vos routes frontend.

Le répertoire database contient votre schéma de base de données ainsi que la déclaration d'un client pour se connecter au service "database" dans le réseau Docker de votre application.

Le répertoire types contient les définitions de types TypeScript partagées par l'ensemble de votre application.

Référez-vous aux pages suivantes pour plus de détails :

rocambille - start-express-react GitHub tag stars - start-express-react

⚠️ **GitHub.com Fallback** ⚠️