Structure des répertoires fr FR

Résumé : 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 !

L'organisation des fichiers

StartER propose une structure de départ robuste, mais non stricte. L'objectif est d'avoir une organisation claire pour vos fichiers frontend et backend, ainsi que la configuration.

Vue détaillée de StartER

.
├── .env
├── .env.sample
├── compose.yaml
├── compose.prod.yaml
├── Dockerfile
├── index.html
├── server.ts
├── data
│   ├── mailpit
│   └── sqlite
│       └── database.sqlite
└── src
    ├── entry-client.tsx
    ├── entry-server.tsx
    ├── database
    │   └── schema.sql
    ├── express
    │   ├── routes.ts
    │   ├── helpers
    │   │   └── ...
    │   └── modules
    │       └── ...
    ├── react
    │   ├── routes.tsx
    │   ├── helpers
    │   │   └── ...
    │   └── components
    │       └── ...
    └── types
        └── index.d.ts

Vous pouvez utiliser le script make:clone fourni avec StartER pour dupliquer des morceaux de cette structure et créer de nouveaux modules ou composants. Ce script n'impose aucun modèle "opinionated" : il vous sert à répliquer vos propres structures et bonnes pratiques.

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. Ce fichier sert de modèle commun pour partager les variables nécessaires sans exposer d'informations sensibles. Après l'installation de StartER, copiez ce fichier .env.sample sous le nom .env.

cp .env.sample .env

Voici les variables recommandées que vous devez renseigner avec vos propres valeurs :

Variable	Description
APP_BASE_URL	URL de base de l'application (utilisée pour les liens magiques).
APP_SECRET	Clé secrète utilisée pour générer la signature pour l'authentification
APP_PORT	(Optionnel) Port d'écoute du serveur de l'application (5173 par défaut)
SMTP_URL	(Optionnel) URL SMTP pour l'envoi d'emails (ex: `smtp://mailpit:1025`)

En développement, une version minimale de votre fichier .env pourrait donc ressembler à ceci :

APP_BASE_URL=http://localhost:5173
APP_SECRET=18a7a18ac0db9b781836f82c080e1c82314b9b56b51f9a914c39cc41113280e8

Note

Grâce à son architecture Zéro-Config avec SQLite, StartER ne requiert aucune variable de configuration pour la base de données.

Tip

Pour générer un APP_SECRET robuste, vous pouvez utiliser la commande suivante dans votre terminal :

openssl rand -hex 32

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

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

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.

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=24

FROM node:${NODE_VERSION}-alpine

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

COPY . .

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

Le fichier .dockerignore exclut les fichiers non nécessaires à la construction de l'image (tels que README, LICENSE...).

Docker est optionnel mais recommandé. En complément du Dockerfile, 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 StartER,
un conteneur mailpit pour capturer localement les emails envoyés par l'application (sans configuration complexe).

Pour créer et démarrer les conteneurs 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 les conteneurs 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 start plutôt que npm run dev.

Pour créer et démarrer les conteneurs en mode production, lancez la commande :

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

Le fichier `index.html`

Le fichier index.html fait référence à entry-client et inclut un marqueur  où le balisage rendu par le serveur est injecté (voir les explications sur un serveur unique de StartER pour les détails [attention : la page est d'un niveau technique plus élevé que le reste du wiki]).

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

<!DOCTYPE html>
<html lang="en">
  <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 un serveur Express et un serveur Vite pour créer un serveur unique.

Le répertoire `src`

La majeure partie de votre application StartER 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 le cœur de votre application StartER. Ils sont organisés de manière similaire :

un dossier helpers contient les outils d'infrastructure (cache, mutations, validation, convertisseurs).
un dossier modules (Express) ou components (React) contient votre logique métier et votre UI.
un fichier routes centralise l'enregistrement de tous les endpoints ou pages de l'application.

Le répertoire database contient votre schéma de base de données (schema.sql), le seeder éventuel (seeder.sql) et la déclaration de la base de données SQLite. Le fichier de base de données local database.sqlite généré à la volée sera hébergé à la racine du projet dans le sous-répertoire data/sqlite/.

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

Ces répertoires constituent la base de votre application StartER.

Bonnes pratiques et cas d'usage

Partagez les variables non sensibles : vous pouvez inclure des variables supplémentaires dans le fichier .env.sample de votre application StartER. 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.
Ne commitez jamais de secrets : votre fichier .env ne doit jamais être ajouté dans un commit avec Git. Chaque poste (machine locale ou serveur) exécutant l'application pourrait avoir besoin d'une configuration d'environnement différente. De plus, cela constituerait un risque critique de sécurité.
Ignorez vos données locales : le répertoire data/ contenant votre base de données et vos emails locaux est intentionnellement ignoré par Git via le fichier .gitignore. Ne le commitez pas pour éviter d'écraser les données locales des autres développeurs.