@nocode-factory/sanity-kit

Outils Sanity Studio de NoCode Factory : Pages (liste + board), Composants, Historique, Design system, aperçu multi-environnements et partage de préversion. Plus, côté site Next.js : garde de préproduction, bascule brouillons / en ligne, bandeau.

Installer

Public sur npmjs, sans jeton. Dans le studio et dans le site :

npm install @nocode-factory/sanity-kit@latest

Un .npmrc qui envoie @nocode-factory vers npm.pkg.github.com est un reste d'avant la 2.0.0 (figé en 1.8.0) : le retirer.

Checklist d'un projet complet

| Où | Quoi | |---|---| | studio/sanity.config.ts | ncfKit(options) ; presentationTool({allowOrigins: ncfAllowedOrigins(options), …}) | | studio/.env (+ .env.production.local) | SANITY_STUDIO_PREVIEW_URL = site en ligne, SANITY_STUDIO_PREVIEW_URL_PREPROD = https://preview-<projet>.vercel.app, SANITY_STUDIO_NCF_PROJECT_KEY | | Vercel | domaine fixe preview-<projet>.vercel.app assigné à la branche preprod ; pas de Vercel Authentication sur les préversions (la garde du kit gère l'accès) | | web/proxy.ts | const guarded = await ncfPreviewGuard(req); if (guarded) return guarded | | web/app/api/draft-mode/toggle/route.ts | export const {GET} = ncfDraftModeToggle() | | layout racine du site | {isPreviewSite() && <NcfPreviewBanner isDraft={isDraft} />} | | .github/workflows/ | captures public/sections/<bloc>.png (workflow du starter) | | Studio | npx ncf-kit setup --types <types de pages> (journal), puis npx sanity deploy | | Studio, schéma | defineComponentDefaults({sections: SECTION_TYPES}) dans schema.types (singleton « Composants : valeurs par défaut ») ; champs obligatoires des sections en requiredUnlessDefault, jamais d'initialValue sur un champ de section | | Studio, Presentation | resolve: {mainDocuments: defineDocuments([componentDefaultsMainDocument({language})])} | | Site, client Sanity | stega: {studioUrl, filter: stegaFilter} | | Site, rendu des sections | applyDefaults(section, defaults, isDraft ? reattributeTo(source, section._key) : undefined) ; défauts lus avec componentDefaultsQuery(types, projection) | | Site, design system | page /design-system/composant?type=<nom> (rendu réel d'un composant, voir le starter) |

Puis, depuis studio/ :

npx ncf-kit doctor

Zéro ✖ = projet complet. Sortie 1 sinon (utilisable en CI).

Design system : la page de tous les styles et composants

La page /design-system du site (option componentPreview.path) est LA page du design system : fondations (couleurs, typographie, grille), marque, icônes et chaque composant rendu avec ses valeurs par défaut. Le bouton Design system de la barre du Studio l'ouvre dans Presentation, avec le document des valeurs par défaut des composants à côté.

Un style changé sur cette page change le composant global : cliquer un composant ouvre ses réglages par défaut, et la modification s'applique partout où une instance ne l'a pas surchargée (pastille bleue sur les champs surchargés).

Côté Studio, lier les pages du design system au document des valeurs par défaut :

presentationTool({resolve: {mainDocuments: defineDocuments([
  ...componentDefaultsMainDocuments({language: 'fr'}), // /design-system et /design-system/composant
])}})

Côté site, la page rend chaque démo avec les valeurs par défaut prioritaires (inherit(defaults[type], demo)), lues dans Sanity : en Presentation, les textes et options proviennent du document des valeurs par défaut, donc cliquables.

Barre du Studio : le kit rend les boutons d'outils. Les outils techniques (Vision, planification « Scheduled drafts » / Releases) sont rangés dans Plus (option moreTools, false pour tout garder en boutons). Ne pas définir de studio.components.toolMenu dans le projet : il masquerait ce menu.

Composants : valeurs par défaut, instances et overrides

Chaque composant (section du page builder) a des valeurs par défaut, réglées dans le document « 🧩 Composants : valeurs par défaut » (un bloc par composant, généré depuis les schémas). Une instance (le composant posé sur une page) dont un champ est vide hérite de la valeur par défaut, et la suit quand elle change. Un champ rempli est un override, jamais écrasé.

Dans le Studio :

• Onglet Composants : un clic sur un composant (grille ou vue Map) ouvre Presentation avec son rendu réel et ses valeurs par défaut côte à côte. Depuis la Map, chaque page listée ouvre le formulaire sur l'instance.
• Propager aux autres langues (publication de la version principale) : structure et valeurs non textuelles appliquées aux brouillons des traductions, textes modifiés marqués « À traduire » (jamais écrasés). Onglet Pages : pastille « À traduire · n » et filtre. Traduction groupée : npx ncf-kit translations (export JSON) puis npx ncf-kit translations apply <fichier> (brouillons, rien de publié).
• Retirer du site (actions d'une page) : dépublie sans rien perdre (contenu gardé en brouillon), après avoir listé les documents qui pointent vers la page.
• Champ Slug d'une page : l'adresse complète de la page en ligne s'affiche dessous (préfixe et langue compris), avec « Copier » et « Ouvrir ».
• Formulaire d'une page : une pastille bleue marque tout champ d'instance différent de la valeur par défaut. Au survol, elle affiche la valeur par défaut ; au clic, le champ revient en héritage. Un champ qui hérite affiche la valeur par défaut (grisée, ou en mention sous les choix).
• Preview : un clic sur un texte hérité ouvre le champ de l'instance.

Les outils de schéma sont aussi dans l'entrée @nocode-factory/sanity-kit/schema, sans interface : c'est elle qu'importent les fichiers de schéma et les scripts (sanity exec).

| API | Où | Rôle | |---|---|---| | defineComponentDefaults({sections}) | @nocode-factory/sanity-kit/schema | type du document des valeurs par défaut | | requiredUnlessDefault | @nocode-factory/sanity-kit/schema | obligatoire sauf valeur par défaut | | componentDefaultsMainDocument({language}) | @nocode-factory/sanity-kit/schema | Presentation : page de rendu = valeurs par défaut | | applyDefaults, inherit | @nocode-factory/sanity-kit/web/defaults | héritage côté site | | componentDefaultsQuery | @nocode-factory/sanity-kit/web/defaults | requête des valeurs par défaut | | stegaFilter, isOptionValue | @nocode-factory/sanity-kit/web/defaults | preview : options jamais encodées | | reattributeTo(source, key) | @nocode-factory/sanity-kit/web/defaults | preview : texte hérité cliquable vers l'instance |

npx ncf-kit doctor vérifie chaque branchement.

Test prod / préprod (bloquant)

Le kit livre le test qui garantit que la production n'affiche jamais de brouillon et que la préproduction reste privée. Dans le package.json du site :

"postbuild": "ncf-kit check-environments"

Après chaque next build (donc à chaque déploiement Vercel), il démarre le site construit en production puis en préproduction simulées et fait 25 contrôles. Un seul échec fait échouer le build : rien n'est mis en ligne. --page <chemin> choisit la page témoin.

Documentation

Dans le dépôt nocode-factory/ncf-sanity-kit : docs/INSTALL.md (options), docs/NOUVEAU-PROJET.md (prompt d'installation), docs/CHANGELOG.md. Le starter nocode-factory/sanity-next-starter est déjà câblé de bout en bout.