Contraintes et limites

Distribution

CStories est publié sur GitHub Packages (voir Installation), ce qui nécessite un token GitHub avec le scope read:packages, même pour des paquets publics. Le dépôt doit être déclaré à la fois dans pluginManagement et dependencyResolutionManagement.

Cibles requises

Appliquer dev.cstories.gradle requiert qu'au moins l'une des cibles jvm() ou wasmJs soit déclarée sur le module. L'appliquer sans aucune des deux échoue immédiatement avec une erreur claire, plutôt que d'en imposer une silencieusement.

Spécificités de wasmJs

wasmJs nécessite que browser() et binaries.executable() soient déclarés explicitement dans votre propre bloc kotlin { } — le plugin ne peut pas reconfigurer cela en toute sécurité une fois la cible finalisée. Voir Lancer le catalogue web pour plus de détails.

Le mode watch du catalogue web (--continuous) déclenche un rechargement complet de la page à chaque modification : l'état de navigation (story sélectionnée, valeurs des contrôles) est perdu à chaque fois, et les rechargements prennent quelques secondes selon la taille du projet. Il n'existe actuellement aucun hot reload préservant l'état pour la cible wasmJs.

Les boutons de copie du catalogue web (onglet Code, exemples de code de l'onglet Docs, commande watch) utilisent le presse-papiers du navigateur, qui n'est disponible que dans un contexte sécurisé : le catalogue doit être servi en HTTPS ou depuis localhost. Sinon, ces boutons n'ont aucun effet.

Page d'accueil

L'introduction de la page d'accueil est lue depuis un fichier nommé exactement CSTORIES.md, à la racine du module qui applique dev.cstories.gradle. Son nom et son emplacement ne sont pas configurables, et un fichier CSTORIES.md placé dans un autre module (par exemple un module de composants) est ignoré. Voir Page d'accueil.

Wrappers de thème

Le wrapper global est un object Kotlin accessible nommé exactement CustomCStoriesThemeWrapper qui implémente CStoriesThemeWrapper. Il est découvert automatiquement. Chaque story peut le surcharger avec @CStory(themeWrapper = WrapperObject::class). Un seul wrapper global peut exister dans le projet agrégé.

Cache de configuration Gradle

dev.cstories.gradle et dev.cstories.gradle.components supportent le cache de configuration de Gradle depuis CStories 2.0.5. Les versions antérieures échouent lorsqu'il est activé et nécessitent --no-configuration-cache.

Références de composants multi-modules

@CStoryComponent n'est visible par KSP que dans le module où il est déclaré. Lorsque composants et stories vivent dans des modules différents, le module de composants doit également appliquer dev.cstories.gradle.components pour que CStoryComponentRefs soit généré. Voir Référencer un composant dans une story.

Modules de bibliothèques publiées

Un module publié comme bibliothèque réutilisable de composants ne doit pas également héberger le catalogue CStories.

Appliquer dev.cstories.gradle ajoute cstories-runtime et les dépendances du catalogue à ce module. Comme Gradle publie les métadonnées de dépendances du module, les consommateurs peuvent être obligés de résoudre des artefacts CStories même s'ils n'utilisent que les composants.

Utilisez plutôt deux modules :

:design-system          // bibliothèque publiée de composants
:design-system:stories  // catalogue et stories, non consommé par les utilisateurs de la bibliothèque

Le module de composants peut utiliser dev.cstories.gradle.components, qui conserve cstories-annotations en dépendance de compilation uniquement. Le module de stories applique dev.cstories.gradle et possède le runtime CStories.