Fichiers seed

Un fichier seed décrit le modèle initial et les données d’exemple optionnelles d’un site EmDash. Les modèles actuels le stockent dans seed/seed.json et y pointent avec package.json#emdash.seed.

EmDash intègre le seed au moment du build. Il est destiné à la première configuration et aux commandes seed explicites, pas comme une migration qui s’exécute à chaque déploiement.

Découverte du fichier

L’intégration Astro cherche un seed dans cet ordre :

1. .emdash/seed.json.
2. Le chemin dans package.json#emdash.seed.
3. seed/seed.json.
4. Le seed par défaut intégré lorsqu’aucun seed utilisateur n’existe.

Le champ de paquet suivant sélectionne le chemin de modèle conventionnel :

{
  "emdash": {
    "seed": "seed/seed.json"
  }
}

Forme racine

L’exemple suivant contient chaque propriété racine :

{
  "$schema": "https://emdashcms.com/seed.schema.json",
  "version": "1",
  "defaultLocale": "en",
  "meta": {
    "name": "Publication",
    "description": "A publication seed",
    "author": "Example Studio"
  },
  "settings": {},
  "blockTypes": [],
  "collections": [],
  "relations": [],
  "taxonomies": [],
  "bylines": [],
  "content": {},
  "menus": [],
  "redirects": [],
  "widgetAreas": [],
  "sections": []
}

defaultLocale doit être une chaîne non vide sans espaces en tête ou en queue.

Settings

settings est un objet partiel de réglages du site. Les propriétés courantes sont title, tagline, logo, favicon, url, postsPerPage, dateFormat, timezone, social et seo.

L’assistant de configuration permet à l’administrateur de remplacer le titre et le slogan seedés. La valeur par défaut onConflict: "skip" conserve ces valeurs lorsque le seed est réappliqué et complète tout réglage fourni encore manquant.

{
  "version": "1",
  "settings": {
    "title": "Field Notes",
    "tagline": "Reports from the team",
    "postsPerPage": 12,
    "dateFormat": "MMMM d, yyyy",
    "timezone": "Europe/London"
  }
}

Types de blocs

blockTypes définit les formes versionnées utilisées par les champs blocks de collection. EmDash applique ces définitions avant les collections, de sorte qu’un champ puisse les nommer dans validation.allowedTypes.

Le seed suivant conserve la version 1 pour le contenu et les révisions stockés tout en rendant la version 2 active pour les nouveaux blocs :

{
  "version": "1",
  "blockTypes": [
    {
      "slug": "hero",
      "label": "Hero",
      "category": "Layout",
      "currentVersion": 2,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string", "required": true }
          ]
        },
        {
          "version": 2,
          "fields": [
            { "slug": "title", "label": "Title", "type": "string", "required": true },
            { "slug": "image", "label": "Image", "type": "image" }
          ]
        }
      ]
    }
  ],
  "collections": [
    {
      "slug": "pages",
      "label": "Pages",
      "fields": [
        {
          "slug": "layout",
          "label": "Layout",
          "type": "blocks",
          "validation": { "allowedTypes": ["hero"], "maxItems": 20 }
        }
      ]
    }
  ]
}

Les numéros de version sont des entiers positifs contigus commençant à 1. currentVersion doit nommer une version déclarée. L’export et la réapplication d’un seed conservent les numéros de version exacts et le pointeur actif ; EmDash ne les renumérote pas.

Avec onConflict: "update", un seed ne peut modifier une version stockée que lorsque la nouvelle définition est compatible. Réutiliser un numéro existant pour une définition incompatible échoue avec BLOCK_TYPE_VERSION_CONFLICT. Ajoutez un nouveau numéro de version pour une définition incompatible.

Les valeurs de bloc stockées incluent _type, _version et _key. Fournissez ces propriétés lorsque le contenu du seed cible une version conservée. Le runtime attribue la version active et une clé lorsqu’un bloc nouvellement écrit les omet.

Collections

Une collection exige slug, label et fields :

{
  "version": "1",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "labelSingular": "Post",
      "description": "Published articles",
      "supports": ["drafts", "revisions", "scheduling", "search", "seo"],
      "urlPattern": "/posts/{slug}",
      "routable": true,
      "commentsEnabled": true,
      "editLocking": true,
      "titleField": "title",
      "dateField": "event_date",
      "admin": {
        "listColumns": ["event_date"]
      },
      "fields": [
        { "slug": "title", "label": "Title", "type": "string", "required": true },
        { "slug": "event_date", "label": "Event date", "type": "datetime", "indexed": true },
        { "slug": "content", "label": "Content", "type": "portableText" }
      ]
    }
  ]
}

Propriétés de collection

sortOrder appartient à la collection et contrôle l’ordre de la barre latérale. SeedField n’a pas de propriété sortOrder. Les champs sont créés dans l’ordre de leur tableau.

Propriétés de champ

Les types de champ pris en charge sont :

• string, text, url et slug.
• number, integer et boolean.
• datetime.
• select et multiSelect.
• portableText, json et repeater.
• blocks.
• image, file et reference.

Un champ reference ne stocke rien dans la table de collection. Ses liens vivent dans la relation à laquelle il est lié ; voir Relations.

Seuls string, url, number, integer, boolean, datetime, select, reference et slug peuvent définir indexed: true. Sur un champ reference, le flag ne s’applique que tant que le champ n’a pas de relation, car un champ lié n’a pas de colonne à indexer.

Validation de champ

Le schéma de collection généré reconnaît ces règles là où le type de champ les prend en charge :

retiredTypes sur un champ blocks est géré côté serveur. Retirer un slug de allowedTypes le met en retraite pour que les blocs stockés existants restent valides tandis que les nouveaux blocs ne peuvent pas l’utiliser.

validateSeed() ne vérifie pas en profondeur chaque règle dans validation ou options. Une règle invalide peut donc passer la validation du seed et échouer plus tard lors de la construction du schéma de collection ou de l’écriture de contenu.

Relations

Une relation joint deux collections et possède les liens entre leurs entrées. Un champ reference se lie à une et voit ses liens depuis une extrémité. Le seed suivant déclare une relation entre posts et authors qui autorise un auteur par article :

{
	"relations": [
		{
			"slug": "post_authors",
			"parentCollection": "posts",
			"childCollection": "authors",
			"parentLabel": "Posts",
			"parentLabelSingular": "Post",
			"childLabel": "Authors",
			"childLabelSingular": "Author",
			"maxChildrenPerParent": 1
		}
	]
}

Un champ reference dans collections nomme la relation à laquelle il se lie :

{
	"slug": "author",
	"label": "Author",
	"type": "reference",
	"validation": { "relation": "post_authors" }
}

Un champ peut nommer un targetCollection à la place et faire créer une relation pour lui, ce qui est le chemin plus court pour un lien qu’une seule collection voit. Déclarez la relation dans relations lorsque les deux collections doivent la voir, ou pour définir ses libellés et limites. reference documente les deux formes et les clés de validation que chacune prend.

Les deux collections d’une relation sont fixes une fois qu’elle existe : un seed qui en nomme d’autres échoue plutôt que de laisser les liens qu’elle détient pointer vers une collection qui n’en est plus une extrémité. Les libellés et limites sont mis à jour lorsque le seed est appliqué avec onConflict: "update".

Taxonomies

Les définitions de taxonomie identifient leurs collections cibles. Les termes sont des données d’exemple et ne sont appliqués que lorsque includeContent est true.

{
  "version": "1",
  "taxonomies": [
    {
      "name": "category",
      "label": "Categories",
      "labelSingular": "Category",
      "hierarchical": true,
      "collections": ["posts"],
      "terms": [
        { "slug": "engineering", "label": "Engineering" },
        { "slug": "platform", "label": "Platform", "parent": "engineering" }
      ]
    }
  ]
}

Une taxonomie peut porter un id local au seed, locale et translationOf. Les termes peuvent aussi porter ces propriétés. translationOf fait référence à un autre ID local au seed. Un terme doit être ordonné après le terme qu’il traduit. Les entrées de taxonomie d’un name peuvent apparaître dans n’importe quel ordre, car l’entrée qui déclare la structure de la taxonomie s’applique avant ses traductions.

hierarchical et collections sont partagés par chaque locale d’une taxonomie, de sorte qu’une entrée de taxonomie dont translationOf pointe vers une entrée du même name peut les omettre. Le moteur d’application suit translationOf à travers les entrées du même name et les prend de la dernière. La validation avertit lorsqu’une traduction déclare des valeurs autres que celles qu’elle prend, ou lorsque deux entrées qui les déclarent pour une taxonomie ne sont pas d’accord. Une taxonomie existante conserve ses valeurs à moins qu’une entrée sans translationOf ne les remplace. Cela se produit avec onConflict: "update", et dans chaque mode lorsque la locale de l’entrée a la définition intégrée non modifiée category ou tag décrite dans Conflict behavior, ou lorsque cette définition intégrée est la seule de la taxonomie. L’export les écrit uniquement sur l’entrée vers laquelle pointent les traductions.

Le parent du terme est le slug du terme parent dans la même locale. Un parent sur une taxonomie non hiérarchique produit un avertissement et est ignoré. Un terme avec translationOf et sans parent prend le parent du terme qu’il traduit.

Bylines

Les bylines racine définissent des crédits de présentation. Ce sont des données d’exemple et exigent includeContent: true.

{
  "version": "1",
  "bylines": [
    {
      "id": "byline-editor",
      "slug": "alex-editor",
      "displayName": "Alex Editor",
      "isGuest": true
    }
  ]
}

L’id est local au seed et est utilisé par les crédits de contenu. Les propriétés optionnelles sont bio, websiteUrl, isGuest et avatar.

Un avatar de byline pointe vers un fichier qui existe déjà dans le stockage configuré :

{
  "id": "byline-editor",
  "slug": "alex-editor",
  "displayName": "Alex Editor",
  "avatar": {
    "storageKey": "avatars/alex.jpg",
    "filename": "alex.jpg",
    "mimeType": "image/jpeg",
    "alt": "Alex Editor",
    "width": 400,
    "height": 400
  }
}

Le seeding d’avatar de byline crée ou réutilise une ligne multimédia pour la clé de stockage. Il ne téléverse ni ne télécharge le fichier.

Content

content groupe les entrées par slug de collection. Chaque entrée exige un id local au seed et un objet data. Les collections routable exigent aussi un slug non vide.

{
  "version": "1",
  "content": {
    "posts": [
      {
        "id": "post-welcome",
        "slug": "welcome",
        "status": "published",
        "data": {
          "title": "Welcome",
          "content": []
        },
        "taxonomies": {
          "category": ["engineering"]
        },
        "bylines": [
          { "byline": "byline-editor", "roleLabel": "Editor" }
        ]
      }
    ]
  }
}

Pour une entrée routable, l’id local au seed n’est pas son identité de base de données. EmDash crée un ID de base de données et enregistre le mappage pour les références ultérieures. Pour une entrée sans slug dans une collection avec routable: false, EmDash utilise l’id du seed comme ID stocké afin que la réapplication reste idempotente.

À la lecture, entry.id est l’identifiant de route Astro et est normalement le slug. L’ID de base de données stocké est entry.data.id.

Références de contenu

Utilisez une chaîne $ref: dans data pour remplacer un ID de contenu local au seed par l’ID de base de données créé :

{
  "id": "event-opening",
  "slug": "opening-night",
  "data": {
    "title": "Opening night",
    "venue": "$ref:venue-main-hall"
  }
}

Les cibles de référence doivent apparaître assez tôt pour être présentes dans la carte d’ID du moteur d’application. Une valeur $ref: non résolue reste la chaîne littérale d’origine ; validateSeed() ne la rejette pas.

Pour un champ reference, déclarez les liens depuis l’extrémité parent de sa relation. Les deux extrémités voient un ensemble de liens, de sorte qu’un champ sur la collection enfant restaterait des liens que le parent porte déjà.

Références multimédias

Utilisez $media dans les données de contenu pour télécharger une URL, la téléverser avec l’adaptateur de stockage fourni, créer une ligne multimédia et remplacer l’objet par une valeur de champ multimédia :

{
  "featured_image": {
    "$media": {
      "url": "https://example.com/images/launch.jpg",
      "filename": "launch.jpg",
      "alt": "A product launch on stage",
      "caption": "Launch event"
    }
  }
}

Dans un bloc Portable Text image ou une image de gallery, $media dans asset devient une référence multimédia (_type: "reference", _ref, url, provider), et le texte alternatif et les dimensions des médias remplissent le propre alt, width et height de l’image lorsqu’ils manquent.

Au sein d’un appel d’apply, les références répétées à la même URL réutilisent la valeur multimédia résolue. Les références multimédias du seed n’acceptent pas de propriété file locale. mediaBasePath reste dans le type public SeedApplyOptions, mais le moteur d’apply actuel ne le lit pas.

Lorsqu’aucun adaptateur de stockage n’est fourni, les références $media sont ignorées et se résolvent en null. Avec skipMediaDownload: true, elles deviennent des valeurs multimédias externes et aucun adaptateur de stockage n’est requis.

Menus

Les menus sont des données structurelles et sont appliqués même lorsque includeContent est false :

{
  "version": "1",
  "menus": [
    {
      "name": "primary",
      "label": "Primary navigation",
      "items": [
        {
          "type": "page",
          "label": "About",
          "ref": "page-about",
          "collection": "pages"
        },
        {
          "type": "custom",
          "label": "Contact",
          "url": "/contact",
          "target": "_self"
        }
      ]
    }
  ]
}

Les types d’éléments autorisés sont custom, page, post, taxonomy et collection. custom exige url ; page et post exigent ref. Les éléments peuvent inclure id, translationOf, label, collection, titleAttr, cssClasses, locale, target et des children imbriqués.

Pour page et post, ref nomme un ID de contenu du seed. Une cible manquante produit un avertissement de validation et un élément de menu sans référence de contenu résolue. Les éléments de menu existants sont supprimés et recréés chaque fois que ce menu est appliqué, indépendamment de onConflict.

Redirects

Les redirections exigent des chemins source et destination locaux :

{
  "version": "1",
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "type": 308,
      "enabled": true,
      "groupName": "WordPress migration"
    }
  ]
}

Les deux chemins doivent commencer par un /. Les URL relatives au protocole, les segments de path traversal et les sauts de ligne sont rejetés. Les codes d’état autorisés sont 301, 302, 307 et 308.

Zones de widgets

Une zone de widgets contient des widgets content, menu ou component :

{
  "version": "1",
  "widgetAreas": [
    {
      "name": "sidebar",
      "label": "Sidebar",
      "widgets": [
        {
          "type": "menu",
          "title": "Explore",
          "menuName": "primary"
        },
        {
          "type": "component",
          "title": "Recent posts",
          "componentId": "core:recent-posts",
          "props": { "count": 5 }
        }
      ]
    }
  ]
}

Un widget de contenu stocke du Portable Text dans content. Un widget de menu exige menuName. Un widget de composant exige componentId et peut passer props. Il n’y a pas de propriété settings sur SeedWidget.

Les widgets existants dans une zone sont supprimés et recréés chaque fois que la zone est appliquée, indépendamment de onConflict.

Sections

Les sections contiennent du contenu Portable Text réutilisable :

{
  "version": "1",
  "sections": [
    {
      "slug": "newsletter-signup",
      "title": "Newsletter signup",
      "description": "Signup call to action",
      "keywords": ["newsletter", "email"],
      "source": "theme",
      "content": []
    }
  ]
}

Les slugs de section contiennent des lettres minuscules, des chiffres et des tirets. source est theme, user ou import ; un seed le définit par défaut à theme. Les sections de thème ne peuvent pas être supprimées dans l’administration. Les sections sont structurelles et sont appliquées même lorsque includeContent est false.

Localisation

defaultLocale remplit les locales manquantes pour les taxonomies, termes, menus, éléments de menu et contenu. La configuration i18n runtime active a la priorité lorsqu’elle est présente.

Les taxonomies, termes, menus, éléments de menu et contenu localisés utilisent les champs id et translationOf locaux au seed. Placez l’élément source avant une traduction pour que le moteur d’application puisse résoudre son groupe de traduction. Une entrée de contenu traduite doit définir locale, et son translationOf doit nommer une autre entrée dans la même collection.

Appliquer un seed de façon programmatique

applySeed() et validateSeed() sont exportés depuis emdash/seed. L’helper suivant valide avant d’appliquer :

import {
  applySeed,
  validateSeed,
  type SeedApplyOptions,
  type SeedFile,
} from "emdash/seed";

type SeedDatabase = Parameters<typeof applySeed>[0];

export async function applyProjectSeed(
  db: SeedDatabase,
  seed: SeedFile,
  options: SeedApplyOptions,
) {
  const validation = validateSeed(seed);
  if (!validation.valid) {
    throw new Error(validation.errors.join("\n"));
  }

  return applySeed(db, seed, options);
}

SeedApplyOptions

L’application programmatique définit includeContent à false par défaut. L’assistant de configuration passe le choix de contenu d’exemple de l’administrateur. La CLI emdash seed inclut le contenu par défaut sauf si --no-content est défini.

Comportement de conflit

onConflict n’est pas une politique de transaction pour tout le seed :

• Collections, champs, bylines, contenu, redirects et sections prennent en charge les comportements skip, update et error.
• Les définitions et termes de taxonomie respectent le mode de conflit applicable. L’exception sont les définitions intégrées category et tag avec lesquelles commence chaque nouvelle base de données : jusqu’à ce qu’un site les modifie, un seed qui les déclare les remplace dans chaque mode.
• Settings utilisent une gestion de conflit par clé. skip crée les réglages manquants et conserve les valeurs existantes. update écrase chaque réglage fourni. error s’arrête au premier réglage existant ; les réglages créés plus tôt dans l’ordre du seed restent appliqués.
• Les menus existants conservent leur ligne de menu mais remplacent tous les éléments.
• Les zones de widgets existantes conservent leur ligne de zone mais remplacent tous les widgets.
• Un conflit de contenu est apparié par collection, slug et locale. Une entrée sans slug dans une collection non routable est appariée par son ID de seed.

Avec onConflict: "update", les données de contenu sont remplacées et ses attributions de byline et de taxonomie sont réconciliées avec le seed. Testez le mode update sur une copie avant de l’utiliser contre un site existant.

applySeed() renvoie des compteurs pour collections, champs, taxonomies, bylines, menus, redirects, zones de widgets, sections, settings, contenu et médias.

Comportement de validation

validateSeed() renvoie { valid, errors, warnings }. applySeed() l’appelle et lance Invalid seed file lorsque des erreurs sont présentes.

Le validateur vérifie les règles structurelles requises par le moteur d’application, notamment :

• Version et defaultLocale non vide.
• Formes de conteneurs de collection, champ, taxonomie, terme, menu, zone de widgets, section, byline et contenu.
• Noms, libellés, IDs, slugs requis et types de champ ou widget pris en charge.
• Identifiants en double dans leur portée pertinente.
• Types de champ indexés et références admin.listColumns.
• Parents de taxonomie, traductions de contenu, références de byline de contenu et exigences d’éléments de menu.
• Chemins de redirection locaux sûrs et codes d’état.

Certaines conditions sont des avertissements plutôt que des erreurs. Exemples : une taxonomie sans collections, un parent sur une taxonomie plate, ou une référence de contenu de menu absente du seed.

Le validateur ne prouve pas que toutes les valeurs data correspondent à leurs champs de collection. Il ne valide pas non plus en profondeur les réglages du site, la validation du champ, les options du champ, les blocs Portable Text arbitraires, les props de widgets de composant, les cibles $ref: dans les données de contenu, ni la disponibilité distante de $media. Un seed valide peut encore échouer pendant la création du schéma, la validation de contenu, le téléchargement réseau ou le téléversement de stockage.

Utilisez l’URL $schema pour l’assistance de l’éditeur et exécutez le validateur exécutable avant d’appliquer :

npx emdash seed seed/seed.json --validate

Commandes CLI

Appliquez un seed à une base SQLite locale avec un comportement de conflit explicite :

npx emdash seed seed/seed.json --database ./data.db --on-conflict skip

Exportez le modèle local actuel et tout le contenu vers le chemin du modèle :

npx emdash export-seed --database ./data.db --with-content=all > seed/seed.json

export-seed travaille directement sur un fichier SQLite local. Pour une base D1 déployée, exportez-la d’abord vers un fichier local. Examinez les réglages, le contenu et les références multimédias exportés avant de valider le résultat. Pour rendre les médias exportés importables sur un autre site, passez --media-base-url ; voir Media URLs.

Étapes suivantes

• Create a theme pour utiliser un seed dans un modèle Astro réutilisable.
• Schema evolution pour mettre à jour le modèle d’un site déployé existant.
• CLI reference pour les options de base de données et d’export.