Installation
DSFR Bundle s'installe dans une application Symfony existante. Le bundle fournit les composants Twig, les types de formulaires et l'intégration profiler ; votre application reste responsable du chargement des fichiers CSS, JavaScript, polices, icônes et favicons du DSFR.
Installez le bundle avec Composer, puis vérifiez séparément deux choses : Twig reconnaît les composants dsfr:*, et les assets DSFR sont bien chargés dans votre layout applicatif.
Prérequis
- PHP 8.3 ou plus récent.
- Symfony 6.4 LTS, 7.4 LTS ou 8.x.
symfony/ux-twig-component.- DSFR 1.14.4 chargé dans le layout de l'application.
Stratégie d'intégration
| Contexte | Recommandation |
|---|---|
| Prototype ou démonstrateur | CDN DSFR accepté temporairement |
| Application publique en production | assets DSFR versionnés dans l'application ou un CDN maîtrisé |
| Projet multi-équipes | layout socle + conventions Twig documentées dès le départ |
| Refonte progressive | commencer par les layouts, formulaires, navigation et feedback |
| Application avec composants Pro | installer la licence avant la recette de préproduction |
Installer le bundle
composer require nalabdou/dsfr-bundle
Si Symfony Flex n'active pas automatiquement le bundle, ajoutez-le dans config/bundles.php :
return [
Nalabdou\Dsfr\DsfrBundle::class => ['all' => true],
];
Installer le DSFR
Le bundle ne force pas une stratégie d'assets. Choisissez celle qui correspond à votre application.
Le point important est la cohérence : CSS, JavaScript, icônes, polices, pictogrammes et favicons doivent provenir de la même version DSFR. Évitez de mélanger CDN, fichiers locaux et versions différentes.
Avec npm
npm install @gouvfr/dsfr@1.14.4
Chargez ensuite les fichiers DSFR depuis votre pipeline front. Les fichiers principaux sont dans node_modules/@gouvfr/dsfr/dist/ :
<link rel="stylesheet" href="{{ asset('build/dsfr/dsfr.min.css') }}">
<link rel="stylesheet" href="{{ asset('build/dsfr/utility/utility.min.css') }}">
<script type="module" src="{{ asset('build/dsfr/dsfr.module.min.js') }}"></script>
<script nomodule src="{{ asset('build/dsfr/dsfr.nomodule.min.js') }}"></script>
Vérifiez aussi que les dossiers fonts, icons et favicon sont publiés avec des chemins compatibles avec le CSS DSFR.
Si vous utilisez dsfr:display ou des composants avec pictogrammes DSFR, publiez aussi le dossier artwork.
Les pictogrammes doivent être accessibles avec le même domaine que la page quand ils sont utilisés via des balises SVG <use>.
Avec AssetMapper ou Webpack Encore
Copiez ou importez les fichiers DSFR dans votre pipeline. L'important est que les chemins finaux restent cohérents :
public/
dsfr/
dsfr.min.css
dsfr.module.min.js
dsfr.nomodule.min.js
utility/utility.min.css
fonts/
icons/
favicon/
artwork/
<link rel="stylesheet" href="{{ asset('dsfr/dsfr.min.css') }}">
<link rel="stylesheet" href="{{ asset('dsfr/utility/utility.min.css') }}">
<script type="module" src="{{ asset('dsfr/dsfr.module.min.js') }}"></script>
<script nomodule src="{{ asset('dsfr/dsfr.nomodule.min.js') }}"></script>
Avec le CDN
Le CDN est acceptable pour valider rapidement une intégration, mais une application publique en production doit privilégier des assets versionnés et maîtrisés par l'équipe projet.
Le CDN est pratique pour un prototype. Pour une application de production, préférez des assets versionnés et servis par votre application ou votre CDN interne.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gouvfr/dsfr@1.14.4/dist/dsfr.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gouvfr/dsfr@1.14.4/dist/utility/utility.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@gouvfr/dsfr@1.14.4/dist/dsfr.module.min.js"></script>
<script nomodule src="https://cdn.jsdelivr.net/npm/@gouvfr/dsfr@1.14.4/dist/dsfr.nomodule.min.js"></script>
Préparer le layout
Le DSFR recommande l'attribut data-fr-scheme sur la balise HTML si vous utilisez le mode clair/sombre :
<!doctype html>
<html lang="fr" data-fr-scheme="system">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="format-detection" content="telephone=no,date=no,address=no,email=no,url=no">
<title>{% block title %}Mon service{% endblock %}</title>
</head>
<body>
{% block body %}{% endblock %}
</body>
</html>
Les scripts DSFR doivent être chargés après le contenu HTML pour laisser la page se rendre rapidement.
Vérification après installation
php bin/console debug:dsfr-components
php bin/console debug:config dsfr
Contrôlez ensuite une page simple avec :
<twig:dsfr:alert type="success" title="DSFR Bundle installé" text="Les composants Twig sont disponibles." />
Si l'alerte apparaît sans style, les composants sont chargés mais les assets DSFR ne le sont pas. Si Twig ne reconnaît pas twig:dsfr:*, vérifiez l'installation du bundle et de symfony/ux-twig-component.
Premier composant
<twig:dsfr:button label="Enregistrer" />
Les tableaux et objets se passent avec la syntaxe Twig : :
<twig:dsfr:breadcrumb :items="[
{label: 'Accueil', href: '/'},
{label: 'Démarches', href: '/demarches'},
{label: 'Créer une demande', current: true}
]" />
Formulaires Symfony
Le thème DSFR est ajouté automatiquement au pont Twig Form par le bundle. Vous pouvez donc utiliser les types fournis directement :
$builder
->add('email', DsfrInputType::class, [
'label' => 'Adresse électronique',
'help' => 'Format attendu : nom@example.fr',
])
->add('submit', DsfrSubmitType::class, [
'label' => 'Envoyer',
]);
Checklist production
| Point | Attendu |
|---|---|
| Assets | fichiers DSFR servis localement ou par CDN maîtrisé |
| Version | même version DSFR pour CSS, JS, utilitaires, fonts, icons et artwork |
| HTML | lang, viewport, charset et data-fr-scheme présents |
| JavaScript | module et nomodule chargés une seule fois |
| Licence | dsfr:license:validate OK si composants Pro utilisés |
| Recette | pages principales vérifiées dans le profiler DSFR |