Installation fr FR

Résumé : StartER est un framework d'applications web à but pédagogique sur une base React / Express. Que vous soyez novice ou développeur expérimenté, ce guide vous accompagnera pour installer et configurer votre première application StartER en quelques minutes.

Présentation

Un framework web fournit une structure et un point de départ pour la création d'une application, permettant de se concentrer sur la réalisation d'un projet.

Pourquoi StartER ?

De nombreux outils et frameworks existent pour créer une application web. Cependant, nous pensons que StartER est un bon choix pour prototyper des applications web modernes et full-stack tout en restant un outil pour apprendre.

Si vous débutez dans le développement web, ce guide vous aidera à vous familiariser avec les ficelles de l'outil sans vous sentir dépassé.

Si vous êtes à un stade plus avancé, StartER vous offrira une base solide pour approfondir vos connaissances et un terrain de jeu pour faire vos propres expériences.

StartER combine ce que nous pensons être les meilleurs packages de l'écosystème JS pour construire un environnement robuste et agréable. Pour autant, nous accueillons avec bienveillance les discussions et les propositions. Qui sait, peut-être rejoindrez-vous l'équipe de développement de StartER ?

Installation pas à pas

Pré-requis

Avant de créer votre première application StartER, assurez-vous que Git et Node.js sont installés sur votre machine locale. De plus, vous devez posséder un compte GitHub afin de pouvoir utiliser le dépôt StartER comme modèle (template).

Créer une application depuis le modèle

Le dépôt GitHub de StartER est un dépôt template. Pour l'utiliser :

Sur GitHub, accédez à la page principale de StartER (https://github.com/rocambille/start-express-react).
Au-dessus de la liste des fichiers, cliquez sur Use this template et sélectionnez Create a new repository.
Utilisez le menu déroulant Owner pour sélectionner le compte auquel vous souhaitez attribuer le dépôt.
Saisissez un nom pour votre dépôt et une description facultative.
Choisissez la visibilité du dépôt. Pour plus d'informations, consultez About repositories.
Cliquez sur Create repository.

Cloner l'application localement

Maintenant, vous pouvez cloner votre dépôt.

Sur GitHub, accédez à la page principale de votre dépôt.
Au-dessus de la liste des fichiers, cliquez sur <> Code.
Copiez l'URL du dépôt sous "HTTPS", "SSH" ou "GitHub CLI" selon votre habitude.
Ouvrez le terminal sur votre machine.
Changez le répertoire de travail actuel vers l'emplacement où vous souhaitez cloner votre dépôt.
Tapez git clone, puis collez l'URL que vous avez copiée précédemment.
```
git clone git@github.com:YOUR-USERNAME/YOUR-REPOSITORY
```

Appuyez sur Entrée pour créer votre clone local.

$ git clone git@github.com:YOUR-USERNAME/YOUR-REPOSITORY
> Cloning into `Spoon-Knife`...
> remote: Counting objects: 10, done.
> remote: Compressing objects: 100% (8/8), done.
> remove: Total 10 (delta 1), reused 10 (delta 1)
> Unpacking objects: 100% (10/10), done.

Changez le répertoire de travail actuel vers votre clone local.
```
cd YOUR-REPOSITORY
```

Maintenant, vous pouvez installer les dépendances dans le répertoire local node_modules de votre projet.

npm install

Configuration initiale

Selon l'environnement d'exécution de l'application, vous trouverez utile de disposer de valeurs de configuration différentes.

Pour cela, 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_BASE_URL	URL de base de l'application (utilisée pour les liens magiques).
APP_SECRET	Clé secrète utilisée pour signer les jetons d'authentification. Choisissez une chaîne aléatoire longue et complexe.

Note

StartER utilise une architecture "Zéro-Config" avec SQLite, il n'est donc pas nécessaire de configurer un serveur de base de données.

Des variables APP_PORT et SMTP_URL sont disponibles dans le fichier .env.sample mais elles sont optionnelles. Elles permettent de modifier le port du serveur (5173 par défaut) et de configurer un serveur SMTP (désactivé par défaut).

Tip

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

openssl rand -hex 32

Pour une description détaillée de chaque variable et des options avancées, consultez la page Structure des répertoires.

Démarrer l'application

Une fois l'application créée et configurée, générez votre base de données locale (fichier database.sqlite) à partir du schéma fourni par défaut :

npm run database:sync

Nous vous recommandons de vérifier que l'installation et la configuration sont correctes avant de continuer :

npm run install:check

Ensuite, lancez le serveur de développement :

npm run dev

Une fois le serveur démarré, votre application sera accessible dans votre navigateur Web à l'adresse http://localhost:5173.

Tip

Pour tester localement l'envoi d'emails, vous pouvez utiliser Mailpit avec Docker (vous devez avoir Docker Engine installé sur votre machine). Configurez la variable SMTP_URL dans le fichier .env :

SMTP_URL=smtp://mailpit:1025

Vous pouvez démarrer votre application avec Mailpit en utilisant la commande :

docker compose up --build

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. Cela permet aux membres de votre équipe d'identifier facilement la configuration nécessaire.
Ne commitez jamais de secrets : votre fichier .env ne doit jamais être ajouté dans un commit avec Git. Chaque poste (machine locale ou serveur) nécessitant une configuration différente, cela protège vos identifiants sensibles d'éventuelles failles de sécurité.

Voir aussi

Maintenant que vous avez créé votre application StartER, vous vous demandez peut-être ce que vous devez apprendre ensuite. Nous vous recommandons vivement de consulter la documentation suivante :