Adieu @import, bonjour @use : le guide de la transition Sass

Sass est depuis longtemps un outil incontournable des développeurs front-end. En effet, cet outil apporte variables, mixins et modularité à votre CSS. Ce n’est que depuis récemment que CSS refait son retard. Si vous utilisez Sass dans votre projet, il est fort à parier que vous utilisez @import. Et c’est bien normal : cette directive a été pendant des années la méthode standard pour structurer les styles.

Mais voilà, les choses évoluent. Avec l’arrivée de Dart Sass comme implémentation de référence, il était évident qu’une nouvelle manière d’écrire du Sass allait voir le jour. On parle ici du système modulaire, basé sur les directives @use et @forward.

Découvrez donc comment et pourquoi il faut migrer vos @import vers @use.

Pourquoi @import est désormais obsolète ?

La directive @import était très répandue, car elle permettait une organisation pratique des fichiers en Sass. Généralement, on incluait un fichier .scss ou .sass dans un fichier principal, afin de séparer les variables, les mixins, les composants, etc…

Mais cette apparente simplicité de @import comprenait finalement plusieurs pièges :

Chargements multiples

Lorsque vous importez un même fichier dans plusieurs autres, Sass ne vérifie absolument rien. Par conséquent, le fichier est rechargé à chaque appel. On peut donc se retrouver avec des effets de bord, des temps de compilation plus longs voire même des comportements inattendus si des variables ou mixins sont redéfinies par erreur.

Pollution globale

Avec @import, il n’y a pas de namespace et toutes les variables, fonctions et mixins sont injectées dans l’espace global. Résultat : impossible de savoir rapidement d’où provient une variable, et les risques de collisions entre noms augmentent au fur et à mesure du projet.

Difficultés de maintenance

Dans un projet de moyenne ou grande taille, il devient rapidement compliqué de :

• gérer l’ordre des imports,
• comprendre la provenance des définitions
• éviter les doublons
• maintenir une structure propre

Depuis l’adoption de Dart Sass comme implémentation principale, @import est officiellement déprécié. Cela signifie qu’il est toujours pris en charge… mais qu’il finira par être supprimé. Il vaut mieux donc suivre les recommandations de la documentation, et d’utiliser exclusivement le système de modules introduit avec @use.

Qu’est-ce que @use change concrètement ?

Avec l’introduction du système de modules, Sass propose une approche beaucoup plus moderne et structurée afin de gérer vos fichiers. Et au cœur de cette nouvelle approche, on retrouve la fameuse directive @use.

Encapsulation par défaut

Contrairement à @import, @use n’expose rien dans l’espace global. Ainsi, toutes les variables, fonctions et mixins d’un fichier importé son encapsulées dans un namespace.

Exemple :

// _variables.scss
$primary-color: #1a73e8;

// styles.scss
@use 'variables';

.button {
  background-color: variables.$primary-color;
}

Résultat : plus de confusion possible, chaque ressource est reliée à un fichier d’origine.

Chargement unique

Avec @use, Sass s’assure qu’un fichier n’est chargé qu’une seule fois, peu importe le nombre de fois où il est appelé. Fini donc les doublons et les effets de bord indésirables dus à des rechargements multiples.

Namespaces personnalisables

Si le nom du namespace par défaut (souvent basé sur le nom du fichier) ne vous convient pas, vous pouvez définir un alias :

@use 'variables' as var;

.alert {
  color: var.$primary-color;
}

Et si vous voulez intégrer un fichier sans namespace, vous pouvez utiliser as *, mais avec prudence :

@use 'variables' as *; // Attention, ça annule l'encapsulation

Personnalisation avec with

Vous pouvez également passer des valeurs à un module lors de son importation avec @use … with(), pour surcharger des variables configurables avant leur utilisation :

@use 'settings' with (
  $font-size: 18px,
  $primary-color: #e63946
);

Cela permet de créer des modules configurables et réutilisables, sans modifier leur code source.

Et @forward dans tout ça ?

@forward est une directive complémentaire à @use. Elle permet de réexporter les contenus d’un fichier depuis un point central. C’est très utile pour créer un seul fichier d’entrée qui rassemble tous les modules de manière propre.

On y revient en détail dans un instant !

Migrer son code : comment passer de @import à @use

Si vous avez un projet existant avec de nombreux @import, pas de panique. La transition vers @use peut se faire progressivement, et avec méthode.

Voici les étapes recommandées :

Étape 1 : identifier les fichiers partagés

Commencez par repérer les fichiers qui sont importés dans plusieurs autres (exemple : _variables.scss, _mixins.scss, etc…)

Ce sont souvent des fichiers qui :

• contiennent des définitions globales
• sont sujets à des doublons
• peuvent bénéficier immédiatement d’un namespace via @use

Étape 2 : réécrire les imports avec @use

Remplace chaque @import par @use, en ajoutant un alias si nécessaire :

// Avant
@import 'variables';
.button {
  color: $primary-color;
}

// Après
@use 'variables' as var;
.button {
  color: var.$primary-color;
}

Étape 3 : ajouter @forward pour centraliser les modules

Vous pouvez créer un fichier abstracts/index.scss qui réexporte tous vos modules :

// abstracts/_index.scss
@forward 'variables';
@forward 'mixins';
@forward 'functions';

Ensuite, dans votre main.scss, il suffit de faire :

@use 'abstracts' as *;

Cela permet de conserver une syntaxe plus légères, tout en gardant l’encapsulation côté module.

Étape 4 : utiliser l’outil sass-migrator

Sass propose un outil en ligne de commande pour automatiser une grande partie de cette transition :

L’outil :

• remplace automatiquement @import par @use + @forward
• ajoute des namespaces
• adapte les appels aux variables/mixins

Structurer son projet Sass avec le système de modules

Migrer vers @use ne consiste pas seulement à changer des lignes de code. C’est aussi l’occasion de repenser l’architecture de vos fichiers Sass pour tirer pleinement parti du système de modules.

Voici une approche recommandée, inspirée des bonnes pratiques modernes :

scss/
├── abstracts/
│   ├── _variables.scss
│   ├── _mixins.scss
│   ├── _functions.scss
│   └── _index.scss         <-- @forward ici
├── base/
│   ├── _reset.scss
│   ├── _typography.scss
│   └── _index.scss         <-- @forward ici
├── components/
│   ├── _button.scss
│   ├── _card.scss
│   └── _index.scss         <-- @forward ici
├── layout/
│   ├── _grid.scss
│   └── _header.scss
├── pages/
│   └── _home.scss
└── main.scss               <-- Point d’entrée

Utiliser @forward pour centraliser

Chaque dossier peut contenir un fichier _index.scss qui réexporte les autres fichiers avec @forward. Exemple :

// abstracts/_index.scss
@forward 'variables';
@forward 'mixins';
@forward 'functions';

Puis dans main.scss, vous pouvez tout importer en une ligne :

@use 'abstracts' as *;
@use 'base' as *;
@use 'components' as *;

Grâce aux @forward des abstracts, tout est disponible via les namespaces dans le reste du projet :

// _button.scss
.button {
  background: var.$primary-color;
  @include mixins.shadow;
}

Conclusion

La transition de @import à @use représente un véritable tournant pour améliorer la structure, la lisibilité et la performance de votre code Sass. Avec l’arrivée de Dart Sass, cette nouvelle approche devient incontournable pour rester à la pointe des bonnes pratiques de développement. En adoptant @use, vous gagnez en clarté, évitez les conflits de variables et mixins, et bénéficiez d’une gestion plus efficace des dépendances.