Commencer avec VueDsfr

NOTE

Ceci est le guide d̛'utilisation de la bibliothèque. Si vous cherchez à contribuer, se référer au Guide du contributeur.

Si vous recherchez :

le storybook, il est ici : storybook.vue-ds.fr (ou sb.vue-ds.fr ou stories.vue-ds.fr).
l’application de demo avec plusieurs composants utilisés dans une vraie app Vue 3, c’est ici : demo.vue-ds.fr
d’autres éléments de l’écosystème VueDsfr, c’est ici : vue-ds.fr/guide/ecosysteme.

Prérequis

Pour utiliser cette bibliothèque, il vous faudra Vue 3 (et Vue-Router 4). Par conséquent, si vous utilisez Nuxt, il vous faut Nuxt 3 (plus de détails plus loin).

Utiliser create-vue-dsfr (fortement recommandé)

La façon la plus simple de commencer un projet est d’utiliser le package create-vue-dsfr, qui permet de créer un projet NPM avec le nécessaire et suffisant (ou plus, selon votre choix) pour développer un projet utilisant VueDsfr, que ce soit pour Vite (Vue3) ou pour Nuxt (Nuxt3), avec TypeScript et ESLint.

Avec npm :

shell

npm init vue-dsfr

Avec pnpm :

shell

pnpm create vue-dsfr

Avec yarn :

shell

yarn create vue-dsfr

Avec bun :

shell

bun create vue-dsfr

Et suivez les indications de l’assistant.

Ajouter la bibliothèque à un projet existant

DSFR ≥ 1.15 : validation des CGU obligatoire

Depuis la version 1.15, @gouvfr/dsfr embarque un script de pré-installation qui vérifie que vous avez accepté les Conditions Générales d'Utilisation (CGU) du DSFR. VueDsfr distribue @gouvfr/dsfr en dépendance mais ne peut pas valider ces CGU à votre place — c'est à vous, développeur·se utilisant VueDsfr, de le faire.

Sans cette validation, npm install / pnpm install / yarn install / bun install échouera avec un message d'erreur explicite plutôt que de s'installer silencieusement.

Étape 1 — Accepter les CGU du DSFR

Avant d'ajouter VueDsfr à un projet (nouveau ou existant), initialisez/validez le DSFR avec son propre assistant :

shell

npm create @gouvfr/dsfr
# ou
pnpm create @gouvfr/dsfr
# ou
yarn create @gouvfr/dsfr
# ou
bun create @gouvfr/dsfr

Cet assistant vous présente les CGU et écrit un fichier .dsfr.yml à la racine de votre projet (contenant la version des CGU acceptée). Ne supprimez pas ce fichier : il est relu à chaque installation.

CI / intégration continue

Pour un environnement non interactif (CI/CD), vous pouvez court-circuiter la validation avec la variable d'environnement DSFR_ACCEPT_LICENSE=1 (à n'utiliser qu'après avoir vous-même validé les CGU au moins une fois en local) :

shell

DSFR_ACCEPT_LICENSE=1 npm install

Étape 2 — Installer la bibliothèque en tant que dépendance du projet

Afin d'installer la bibliothèque, taper ces commandes dans votre console au sein du répertoire du projet :

shell

npm install @gouvfr/dsfr @gouvminint/vue-dsfr
# ou
pnpm add @gouvfr/dsfr @gouvminint/vue-dsfr
# ou
yarn add @gouvfr/dsfr @gouvminint/vue-dsfr
# ou
bun add @gouvfr/dsfr @gouvminint/vue-dsfr

Pourquoi @gouvfr/dsfr ?

@gouvminint/vue-dsfr utilise le CSS de @gouvfr/dsfr, c’est pourquoi il faut l’installer aussi.

Spécifique à pnpm ≥ 10

Depuis pnpm 10, les scripts d'installation (preinstall/postinstall) des dépendances sont bloqués par défaut pour des raisons de sécurité (supply-chain). Il faut explicitement autoriser celui de @gouvfr/dsfr :

shell

pnpm add @gouvfr/dsfr @gouvminint/vue-dsfr --allow-build=@gouvfr/dsfr

Ou, si @gouvfr/dsfr est déjà présent dans votre lockfile et que pnpm affiche ERR_PNPM_IGNORED_BUILDS :

shell

pnpm approve-builds @gouvfr/dsfr
pnpm install

pnpm approve-builds ajoute (sans écraser le reste de votre configuration) une entrée dans le pnpm-workspace.yaml de votre projet :

yaml

allowBuilds:
  '@gouvfr/dsfr': true

Cette entrée reste valable pour toutes les futures versions de @gouvfr/dsfr : elle autorise l'exécution du script, mais ne dispense pas de la validation des CGU elle-même (voir Étape 1).

⚠️ La commande pnpm create @gouvfr/dsfr --allow-build=... ne fonctionne pas : le flag --allow-build ne s'applique qu'au paquet exécuté via dlx (l'assistant create-dsfr lui-même), pas à l'installation qu'il déclenche ensuite dans le projet généré. Utilisez pnpm approve-builds une fois le projet créé.

Que se passe-t-il si les CGU changent lors d'une mise à jour ?

Chaque version de @gouvfr/dsfr peut référencer une nouvelle version des CGU. Si vous montez de version (@gouvfr/dsfr ou @gouvminint/vue-dsfr) et que la version des CGU a changé, l'installation échouera avec un message du type :

text

[UPDATE-1.0.1->1.1.0] La version des modalités d'utilisation acceptée (1.0.1) ne correspond pas
à la dernière version des modalités d'utilisation (1.1.0). Lancez `pnpm create @gouvfr/dsfr`
pour accepter les modalités d'utilisation à jour.

Il suffit de relancer l'assistant pour régénérer .dsfr.yml avec la nouvelle version acceptée, puis de relancer l'installation :

shell

pnpm create @gouvfr/dsfr

Utiliser la bibliothèque en tant que plugin

Méthode déconseillée

Cette méthode est déconseillée. Elle est présente dans la documentation pour des raisons historiques. Cette méthode est facile à mettre en place et permet de tester rapidement les composants dans une application, cependant, comme elle enregistre tous les composants, ils sont tous présents dans le bundle final, ce qui est loin d’être optimal.

On peut avoir le meilleur des deux mondes (import automatique des composants et un bundle final optimisé qui ne contient que les composants réellement utilisés) avec l’auto-import et le component resolver livrés avec les versions 5.5+ de VueDsfr. C’est le défaut depuis la version 1.7.0 de l’assistant officiel create-vue-dsfr.

Voir plus loin la section correspondante.

Ajouter le plugin

Ajouter la bibliothèque en tant que plugin a deux conséquences :

pros	cons
Pas besoin d’enregistrer les composants qu’on utilise : le plugin les enregistre tous pour nous	Le bundle final sera plus lourd

Dans une application Vite

À partir d'un fichier main.ts simple comme celui-ci :

import { createApp } from 'vue'

import App from './App.vue'

const app = createApp(App)
  .mount('#app')

ajouter les lignes suivantes :

typescript

import { createApp } from 'vue'
import '@gouvfr/dsfr/dist/dsfr.min.css'      // Import des styles du DSFR //
import '@gouvminint/vue-dsfr/styles'         // Import des styles globaux propre à VueDSFR //
import VueDsfr from '@gouvminint/vue-dsfr'   // Import (par défaut) de la bibliothèque //

import App from './App.vue'

const app = createApp(App)
  .use(VueDsfr)                              // Enregistrement de la bibliothèque en tant que plugin //
  .mount('#app')

Dans nuxt 3

Utiliser le module vue-dsfr-nuxt-module et sa documentation (README.md).

Utiliser la bibliothèque de composants sans plugin

Il est possible de ne pas importer tous les composants, et de sélectionner les composants utilisés :

import { createApp } from 'vue'

import App from './App.vue'
import {
  DsfrHeader,
  DsfrButton,
  DsfrBreadcrumb,
  DsfrCard,
  VIcon,
} from '@gouvminint/vue-dsfr'                   // Imports nommés de la bibliothèque

import '@gouvfr/dsfr/dist/dsfr.min.css'         // Import des styles du DSFR
import '@gouvminint/vue-dsfr/styles'            // Import des styles propres à la bibliothèque VueDSFR

const app = createApp(App)
  .component('DsfrHeader', DsfrHeader)          // Enregistrement global du composant DsfrHeader
  .component('DsfrButton', DsfrButton)          // Enregistrement global du composant DsfrButton
  .component('DsfrBreadcrumb', DsfrBreadcrumb)  // Enregistrement global du composant DsfrBreadcrumb
  .component('DsfrCard', DsfrCard)              // Enregistrement global du composant DsfrCard
  .component('VIcon', VIcon)                    // Enregistrement global du composant VIcon
  .mount('#app')

INFO

Il faut enregistrer globalement le composant VIcon si vous voulez l’utiliser comme dans l’exemple ci-dessus, ou bien l’importer dans chaque composant où il sera utilisé.

WARNING

Cette méthode permet de n’avoir dans le bundel final que les composants utilisés dans l’application. Cependant, la DX n’est pas optimale.

Utiliser les icônes

Cf. la page dédiée

Avoir un bundle optimisé et une DX optimale

Il est possible d’intégrer moins de CSS, et de n’importer que les composants réellement utilisés dans votre application, sans avoir à écrire les imports dans votre code, voici quelques notes à ce propos (voir les commentaires dans le code).

Important

Si vous avez utilisé la version 1.7+ de create-vue-dsfr pour créer votre projet, tout ce qui suit est déjà fait !

Vue

Dans le point d’entrée de votre application Vue (souvent main.js ou main.ts) :

typescript

import '@gouvfr/dsfr/dist/core/core.main.min.css' // Le CSS minimal du DSFR
import '@gouvfr/dsfr/dist/component/component.main.min.css' // Styles de tous les composants du DSFR
import '@gouvfr/dsfr/dist/utility/utility.main.min.css' // Classes utilitaires : les composants de VueDsfr en ont besoin
import '@gouvfr/dsfr/dist/scheme/scheme.min.css' // Facultatif : Si les thèmes sont utilisés (thème sombre, thème clair)

import '@gouvminint/vue-dsfr/styles' // Les styles propres aux composants de VueDsfr

Les imports automatiques des composables et des composants

À partir de la version 5.5.0, VueDsfr intègre 3 nouveaux exports pour pouvoir importer automatiquement les composables et autres fonctions et les composants (grâce au plugin vite unplugin-auto-import).

Les imports automatiques des composables et fonctions

Il y a deux presets livrés avec VueDsfr (depuis la v5.5.0 seulement) à utiliser avec le plugin unplugin-auto-import) :

Installer les dépendances de développement :

shell

npm i -D unplugin-auto-import unplugin-vue-components

Ajouter ces lignes dans vite.config.ts :

typescript

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import {
  vueDsfrAutoimportPreset,
  vueDsfrComponentResolver
} from '@gouvminint/vue-dsfr/meta'

const isCypress = process.env.CYPRESS === 'true'

// https://vitejs.dev/config/
export default defineConfig({
  base: process.env.BASE_URL || '/',
  plugins: [
    vue(),
    vueJsx(),
    AutoImport({
      include: [
        /\.[tj]sx?$/,
        /\.vue$/, /\.vue\?vue/,
      ],
      imports: [
        'vue',
        'vue-router',
        ...(isCypress ? [] : ['vitest']),
        vueDsfrAutoimportPreset,       // Autoimport des composables de VueDsfr
      ],
      vueTemplate: true,
      dts: './src/auto-imports.d.ts',
      eslintrc: {
        enabled: true,
        filepath: './.eslintrc-auto-import.json',
        globalsPropValue: true,
      },
    }),
    // Autoimport des composants utilisés dans les templates
    Components({
      extensions: ['vue'],
      dirs: ['src/components'],        // Autoimport de vos composants qui sont dans le dossier `src/components`
      include: [/\.vue$/, /\.vue\?vue/],
      dts: './src/components.d.ts',
      resolvers: [
        vueDsfrComponentResolver,      // Autoimport des composants de VueDsfr dans les templates
      ],
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

Voici ce que cela permet :

main.ts avec auto-importsmain.ts sans auto-importsApp.vue avec auto-importsApp.vue sans auto-imports

import App from './App.vue'
import router from './router/index'

import '@gouvfr/dsfr/dist/dsfr.main.min.css'

import '@gouvfr/dsfr/dist/utility/utility.main.min.css'
import '@gouvminint/vue-dsfr/styles'

import './main.css'

createApp(App) // createApp est autoimporté grâce au preset 'vue' dans vite.config.ts
  .use(router)
  .mount('#app')

typescript

import '@gouvfr/dsfr/dist/dsfr.main.min.css'
import '@gouvfr/dsfr/dist/utility/utility.main.min.css'

import '@gouvminint/vue-dsfr/styles'

import { createApp } from 'vue'
import { VIcon } from '@gouvminint/vue-dsfr' // Facultatif : uniquement si vous utilisez VIcon dans votre projet

import App from './App.vue'
import router from './router/index'
import * as icons from './icons'

import './main.css'

createApp(App)
  .component('VIcon', VIcon) // Facultatif : uniquement si vous utilisez VIcon dans votre projet
  .use(router)
  .mount('#app')

vue

<script setup lang="ts">
useScheme() // Autoimporté grâce à vueDsfrAutoimportPreset dans vite.config.ts

const serviceTitle = 'Service'
const serviceDescription = 'Description du service'
const logoText = ['Ministère', 'de l’intérieur']

const quickLinks = [
  // (...)
]
const searchQuery = ref('')
</script>

<template>
  <!-- DsfrHeader est autoimporté grâce à vueDsfrComponentResolver dans vite.config.ts -->
  <DsfrHeader
    v-model="searchQuery"
    :service-title="serviceTitle"
    :service-description="serviceDescription"
    :logo-text="logoText"
    :quick-links="quickLinks"
    show-search
  />

  <div class="fr-container  fr-mt-3w  fr-mt-md-5w  fr-mb-5w">
    <RouterView />
  </div>
</template>

vue

<script setup lang="ts">
import { DsfrHeader, useScheme } from '@gouvminint/vue-dsfr'

useScheme()

const serviceTitle = 'Service'
const serviceDescription = 'Description du service'
const logoText = ['Ministère', 'de l’intérieur']

const quickLinks = [
  // (...)
]
const searchQuery = ref('')
</script>

<template>

  <DsfrHeader
    v-model="searchQuery"
    :service-title="serviceTitle"
    :service-description="serviceDescription"
    :logo-text="logoText"
    :quick-links="quickLinks"
    show-search
  />

  <div class="fr-container  fr-mt-3w  fr-mt-md-5w  fr-mb-5w">
    <RouterView />
  </div>
</template>

Nuxt

CGU du DSFR

Avant d'installer les dépendances, assurez-vous d'avoir accepté les CGU du DSFR. Sans le fichier .dsfr.yml, l'installation échouera.

Ajouter les dépendances @gouvfr/dsfr et @gouvminint/vue-dsfr au projet

bash

# Avec pnpm
pnpm add @gouvfr/dsfr @gouvminint/vue-dsfr

# Avec yarn
yarn add @gouvfr/dsfr @gouvminint/vue-dsfr

# Avec npm
npm i @gouvfr/dsfr @gouvminint/vue-dsfr

# Avec bun
bun add @gouvfr/dsfr @gouvminint/vue-dsfr

Ajouter le CSS de DSFR et de VueDsfr dans la section css de nuxt.config.ts

export default defineNuxtConfig({
  css: [
    '@gouvfr/dsfr/dist/core/core.main.min.css',           // Le CSS minimal du DSFR
    '@gouvfr/dsfr/dist/component/component.main.min.css', // Styles de tous les composants du DSFR
    '@gouvfr/dsfr/dist/utility/utility.main.min.css',     // Classes utilitaires : les composants de VueDsfr en ont besoin, contient aussi les icônes

    '@gouvfr/dsfr/dist/scheme/scheme.min.css',            // Facultatif : Si les thèmes sont utilisés (thème sombre, thème en berne)

    '@gouvminint/vue-dsfr/styles',                        // Styles des composants VueDsfr
  ],
})

Et voilà ! Vous êtes prêts à utiliser VueDsfr dans votre app Nuxt ✨

Commencer avec VueDsfr ​

Utiliser create-vue-dsfr (fortement recommandé) ​

Ajouter la bibliothèque à un projet existant ​

Étape 1 — Accepter les CGU du DSFR ​

Étape 2 — Installer la bibliothèque en tant que dépendance du projet ​

Que se passe-t-il si les CGU changent lors d'une mise à jour ? ​

Utiliser la bibliothèque en tant que plugin ​

Ajouter le plugin ​

Dans une application Vite ​

Dans nuxt 3 ​

Utiliser la bibliothèque de composants sans plugin ​

Utiliser les icônes ​

Avoir un bundle optimisé et une DX optimale ​

Vue ​

Les imports automatiques des composables et des composants ​

Les imports automatiques des composables et fonctions ​

Nuxt ​

Commencer avec VueDsfr

Utiliser create-vue-dsfr (fortement recommandé)

Ajouter la bibliothèque à un projet existant

Étape 1 — Accepter les CGU du DSFR

Étape 2 — Installer la bibliothèque en tant que dépendance du projet

Que se passe-t-il si les CGU changent lors d'une mise à jour ?

Utiliser la bibliothèque en tant que plugin

Ajouter le plugin

Dans une application Vite

Dans nuxt 3

Utiliser la bibliothèque de composants sans plugin

Utiliser les icônes

Avoir un bundle optimisé et une DX optimale

Vue

Les imports automatiques des composables et des composants

Les imports automatiques des composables et fonctions

Nuxt