Kit de développement frontend Vue.js permettant de créer des sites thématiques ("verticales") spécialisés basés sur l'écosystème data.gouv.fr. Ce framework fournit les composants, la configuration et l'architecture nécessaires pour déployer rapidement des verticales dédiées à des domaines spécifiques (écologie, météo, défis, etc.).

Chaque verticale est configurée dans un fichier config.yaml stocké sous configs/$verticale.

La variable d'environnement VITE_SITE_ID permet de définir la configuration utilisée au lancement de l'application. Cette variable peut être définie dans le fichier .env ou ses dérivés.

VSCode + Vue - Official + ESLint

Ce projet utilise pnpm au lieu de npm. Si vous ne l'avez pas déjà installé :

# Enable pnpm via Corepack (inclus avec Node.js 20+)
corepack enable pnpm

Il existe d'autres méthodes d'installation si besoin.

pnpm install
# vous pouvez ignorer ici les éventuels warnings de type "pnpm approve-builds"

# installe les pre-commit hooks Husky
pnpm run prepare

pnpm run dev

pnpm run build

pnpm run test

En environnement de dev :

Pour lancer les tests génériques communs à tous les sites, qui se trouvent dans /cypress/e2e/ :

# Pour lancer la version ligne de commande de cypress :
pnpm run test:e2e

# Pour lancer la version visuelle de cypress :
pnpm run test:e2e:open

Pour lancer les tests génériques + les tests spécifiques à site particulier qui se trouvent dans /cypress/e2e/monsite/ :

# Pour lancer la version ligne de commande de cypress :
VITE_SITE_ID=monsite pnpm run test:e2e

# Pour lancer un seul test en ligne de commande :
VITE_SITE_ID=monsite pnpm run test:e2e -- --spec cypress/e2e/my/file.cy.js

# Pour lancer la version visuelle de cypress :
VITE_SITE_ID=monsite pnpm run test:e2e:open

Tester un build :

Dans la CI, on veut lancer les tests sur un build, plutôt que sur un serveur de dev.

# Build pour monsite
VITE_SITE_ID=monsite pnpm run build
# Run les tests sur le build de monsite
VITE_SITE_ID=monsite pnpm run test:e2e:for_production_build

Afin de ne pas dépendre de données extérieures pour faire tourner les tests, il est recommandé de "mocker" ou "bouchonner" vos appels APIs.

On utilise la librairie mimicry-js comme factory pour créer des données pour ces mocks.

pnpm run lint

pnpm run hint

pnpm run format

Ce projet utilise pnpm au lieu de npm principalement pour des raisons de sécurité :

• bloque par défaut les scripts d'installation des dépendances (sauf Cypress et Husky via onlyBuiltDependencies),
• période de cooldown de 4 jours (minimum-release-age) avant d'installer les nouveaux packages, laissant le temps à la communauté de détecter les versions malveillantes,
• installation via le lockfile par défaut (npm ci like),
• ... et d'autres valeurs de configurations par défaut plus saines que celles de npm.

pnpm promet également de meilleurs performances à l'installation et un usage réduit d'espace disque. On ne bénéficie malheureusement pas (encore) de la structure "non-flat" des node_modules pour des raisons de rétro-compatibilité avec certaines dépendances.

Une review app est un environnement de prévisualisation temporaire qui permet de tester les changements d'une Pull Request dans un environnement similaire à la production. Un workflow CI/CD dédié (.github/workflows/review-app.yml) gère automatiquement la création, mise à jour et suppression de ces environnements.

Les review apps ne sont pas créées automatiquement lors de l'ouverture d'une Pull Request. L'auteur de la PR doit déployer manuellement les PR qu'il souhaite tester, via l'interface de GitHub Actions.

💡 Info : Une fois qu'une review app est créée pour une PR, elle sera automatiquement mise à jour à chaque nouveau commit sur la PR.

URLs générées : https://deploy-preview-{PR_NUMBER}--{SITE}.sandbox.data.developpement-durable.gouv.fr

1. Ecrire un commentaire du type /deploy {SITE} dans la PR (e.g. /deploy ecospheres)
2. Une emoji 🚀 apparaîtra sous le commentaire pour indiquer que le déploiement est lancé.
3. Une notification du type @github-actions github-actions bot deployed to ecospheres-preview sur le fil de la PR indiquera que le déploiement est terminé, avec un lien vers le déploiement.

1. Aller dans l'onglet "Actions" du dépôt GitHub
2. Sélectionner "Deploy review app" dans la liste des workflows
3. Cliquer sur "Run workflow"
4. Choisir :
   • Branch : Le nom de la branche à déployer, correspondant à votre PR
   • Site : Le site à déployer (dropdown)
   • Pull Request number : Le numéro de votre PR
5. Cliquer sur "Run workflow"

Le déploiement des verticales thématiques en preprod et en production s'effectue via un workflow GitHub qui peut être déclenché de deux manières différentes :

Le déploiement des verticales thématiques en preprod et en production peut s'effectuer via un workflow GitHub qui se déclenche automatiquement à partir du message de commit. Le format du message de commit doit être :

[<environment>:<site>:<version_type>] <description>

Paramètres :

• <environment> : Environnement cible (prod ou demo/preprod suivant la verticale)
• <site> : Nom du site
  • Sites disponibles :
    • ecospheres - Site écologie
    • meteo-france - Site météo
    • logistique - Site logistique
    • defis - Site défis
    • hackathon - Site hackathon
    • simplifions - Site simplifions
• <version_type> : Type de version (major, minor, ou patch)

Exemple :

[prod:ecologie:minor] nouvelle fonctionnalité incroyable

Le workflow se déclenche sur tous les push vers toutes les branches, mais ne s'exécute que si le message de commit commence par [ (condition startsWith(github.event.head_commit.message, '[')). Cette condition n'est pas parfaite mais GitHub Actions ne supporte pas directement le déclenchement de workflows basé sur des expressions régulières dans les messages de commit.

Toutes les variables et secrets nécessaires pour ce workflow sont listés dans la section env: du workflow de déploiement.

Le déploiement peut également être déclenché manuellement via l'interface GitHub Actions :

1. Aller dans l'onglet "Actions" du dépôt GitHub
2. Sélectionner "Deployment on datagouv domains with version bump" dans la liste des workflows
3. Cliquer sur "Run workflow"
4. Choisir :
   • Site : Le site à déployer (dropdown avec les sites disponibles)
   • Environment : L'environnement cible (demo, preprod, ou prod)
   • Version type : Le type de version (major, minor, ou patch)
5. Cliquer sur "Run workflow"

Pour des raisons de sécurité, le déploiement est effectué par un dépôt privé GitLab dédié à l'infrastructure. Le processus fonctionne ainsi :

1. GitHub Actions : Les actions sur GitHub déclenchent le workflow
2. GitHub Actions : Calcul de la prochaine version basée sur les tags existants
3. GitHub Actions : Création d'un nouveau tag avec cette version. Le tag créé est utilisé lors de la construction de l'image et pendant le déploiement.
4. GitHub Actions : Appels à l'API GitLab via un script téléchargé depuis le dépôt "scaffolding"
5. GitLab CI/CD : Le script déclenche ensuite le pipeline de déploiement sur GitLab

Note : Pour cette raison il n'est pas encore possible de suivre le détail de l'avancement du déploiement directement depuis GitHub Actions (#TODO)

⚠️ Cette section est une recommandation, chaque verticale/site est libre de définir ses propres processus.

• La branche main recueille les fonctionnalités au fur et à mesure de leur développement.
• La branche {site}-preprod est utilisée pour les déploiements sur https://{site}.preprod.data.gouv.fr.
  • On commence par créer une Pull Request depuis main vers {site}-preprod ;
  • Une fois cette PR validée, on déploie soit via un message de commit normé soit via l'UI GitHub Actions (cf plus haut).
• La branche {site}-prod est utilisée pour les déploiements sur https://{site}.data.gouv.fr.
  • Même processus que pour la preprod, mais en créant une PR depuis {site}-preprod vers {site})-prod.

NB : dans certains cas, il possible de créer et de déployer des Pull Requests depuis une feature branch vers {site}-(pre)prod, par exemple pour définir une configuration spécifique à l'environnement de preprod ou de prod.

• @datagouv/components - Composants officiels de data.gouv.fr
• @gouvminint/vue-dsfr - Intégration Vue.js du Design System de l'État
• @gouvfr/dsfr - Design System de l'État Français
• @vueuse/core - Utilitaires Vue.js (useTitle, etc.)
  • @vueuse/integrations - Intégrations supplémentaires de VueUse (focustrap)
• unplugin-auto-import - Auto-import d'API Vue.js et vue-dsfr
• unplugin-vue-components - Auto-import des composants custom et vue-dsfr
• @unhead/vue - Gestion du SEO et des métadonnées

• eslint - eslint.config.mjs
  • typescript-eslint
  • eslint-plugin-json
  • eslint-plugin-vue
• prettier - .prettierrc.mjs
  • prettier-plugin-organize-imports // organise et/ou supprime les imports des fichiers

À chaque git commit, husky lance lint-staged qui formate les fichiers "staged" avec prettier.

Après avoir créé votre projet (VueJs) sur sentry, voici la configuration à ajouter à votre fichier de config pour activer Sentry dans votre projet :

sentry:
  domain_url: 'https://errors.data.gouv.fr/' # Ou tout autre domaine où vous hébergez votre sentry
  dsn: 'https://[email protected]/38' # Vous trouverez ce DSN lors de l'initialisation de votre projet dans Sentry
  environment: 'preprod' # Ou autre (par exemple 'production'), selon la branche de déploiement

D'autres éléments de configuration sont disponibles dans le fichier src/model/config.ts

• data.gouv.fr, Direction interministérielle du numérique.
• Ecolab, Commissariat général au développement durable, Ministère en charge de l’environnement.

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

• Issues : GitHub Issues
• Formulaire de contact : Formulaire de support