Contraintes et limites

Distribution

CStories est actuellement publié uniquement dans mavenLocal(). Il n'y a pas encore de dépôt distant, donc chaque projet consommateur doit déclarer mavenLocal() à 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.

Wrappers de thème

Le wrapper global est un object Kotlin accessible nommé 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é.

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.