Seed-Dateien

Eine Seed-Datei beschreibt das Anfangsmodell und optionale Beispieldaten für eine EmDash-Site. Aktuelle Templates speichern sie unter seed/seed.json und verweisen darauf mit package.json#emdash.seed.

EmDash bettet den Seed zur Build-Zeit ein. Er ist für die erste Einrichtung und explizite Seed-Befehle gedacht, nicht als Migration, die bei jedem Deployment läuft.

Dateierkennung

Die Astro-Integration sucht in dieser Reihenfolge nach einem Seed:

1. .emdash/seed.json.
2. Der Pfad in package.json#emdash.seed.
3. seed/seed.json.
4. Der integrierte Standard-Seed, wenn kein Benutzer-Seed existiert.

Das folgende Paketfeld wählt den üblichen Template-Pfad:

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

Root-Form

Das folgende Beispiel enthält jede Root-Eigenschaft:

{
  "$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 muss ein nicht leerer String ohne führende oder nachgestellte Leerzeichen sein.

Einstellungen

settings ist ein teilweises Site-Einstellungsobjekt. Häufige Eigenschaften sind title, tagline, logo, favicon, url, postsPerPage, dateFormat, timezone, social und seo.

Der Einrichtungsassistent lässt den Administrator den per Seed gesetzten Titel und Untertitel ersetzen. Das Standardverhalten onConflict: "skip" bewahrt diese Werte, wenn der Seed erneut angewendet wird, und ergänzt alle gelieferten Einstellungen, die noch fehlen.

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

Block-Typen

blockTypes definiert die versionierten Formen, die von blocks-Collection-Feldern verwendet werden. EmDash wendet diese Definitionen vor den Collections an, sodass ein Feld sie in validation.allowedTypes benennen kann.

Der folgende Seed behält Version 1 für gespeicherten Inhalt und Revisionen bei und macht Version 2 für neue Blöcke aktiv:

{
  "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 }
        }
      ]
    }
  ]
}

Versionsnummern sind positive, lückenlose ganze Zahlen, die bei 1 beginnen. currentVersion muss eine deklarierte Version benennen. Das Exportieren und erneute Anwenden eines Seeds bewahrt die exakten Versionsnummern und den Zeiger auf die aktive Version; EmDash nummeriert nicht neu.

Mit onConflict: "update" kann ein Seed eine gespeicherte Version nur ändern, wenn die neue Definition kompatibel ist. Wird eine vorhandene Nummer für eine inkompatible Definition wiederverwendet, schlägt dies mit BLOCK_TYPE_VERSION_CONFLICT fehl. Fügen Sie für eine inkompatible Definition eine neue Versionsnummer hinzu.

Gespeicherte Blockwerte enthalten _type, _version und _key. Geben Sie diese Eigenschaften an, wenn Seed-Inhalt eine beibehaltene Version anspricht. Die Laufzeit weist die aktive Version und einen Schlüssel zu, wenn ein neu geschriebener Block sie weglässt.

Collections

Eine Collection erfordert slug, label und 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" }
      ]
    }
  ]
}

Collection-Eigenschaften

sortOrder gehört zur Collection und steuert die Reihenfolge in der Seitenleiste. SeedField hat keine Eigenschaft sortOrder. Felder werden in der Reihenfolge ihres Arrays erstellt.

Feld-Eigenschaften

Unterstützte Feldtypen sind:

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

Ein reference-Feld speichert nichts in der Collection-Tabelle. Seine Links liegen in der Relation, an die es gebunden ist; siehe Relationen.

Nur string, url, number, integer, boolean, datetime, select, reference und slug können indexed: true setzen. Bei einem reference-Feld gilt das Flag nur, solange das Feld keine Relation hat, da ein gebundenes Feld keine Spalte zum Indexieren besitzt.

Feldvalidierung

Das generierte Collection-Schema erkennt diese Regeln dort, wo der Feldtyp sie unterstützt:

retiredTypes an einem Blocks-Feld wird vom Server verwaltet. Wird ein Slug aus allowedTypes entfernt, wird er ausgemustert: Vorhandene gespeicherte Blöcke bleiben gültig, neue Blöcke können ihn aber nicht verwenden.

validateSeed() prüft nicht jede Regel in validation oder options tiefgehend auf ihren Typ. Eine ungültige Regel kann daher die Seed-Validierung bestehen und später fehlschlagen, wenn das Collection-Schema gebaut oder Inhalt geschrieben wird.

Relationen

Eine Relation verbindet zwei Collections und besitzt die Links zwischen ihren Einträgen. Ein Reference-Feld bindet an eine Relation und sieht ihre Links von einem Ende aus. Der folgende Seed deklariert eine Relation zwischen posts und authors, die einen Autor pro Beitrag erlaubt:

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

Ein Reference-Feld in collections benennt die Relation, an die es gebunden wird:

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

Ein Feld kann stattdessen eine targetCollection benennen und dafür eine Relation erstellen lassen. Das ist der kürzere Weg für einen Link, den nur eine Collection sieht. Deklarieren Sie die Relation in relations, wenn beide Collections sie sehen sollen oder um ihre Labels und Limits festzulegen. reference dokumentiert beide Formen und die Validierungsschlüssel, die jede von ihnen annimmt.

Die beiden Collections einer Relation sind fest, sobald sie existiert: Ein Seed, der andere benennt, schlägt fehl, statt die Links, die sie hält, auf eine Collection zeigen zu lassen, die kein Ende der Relation mehr ist. Labels und Limits werden aktualisiert, wenn der Seed mit onConflict: "update" angewendet wird.

Taxonomies

Taxonomy-Definitionen bezeichnen ihre Ziel-Collections. Terms sind Beispieldaten und werden nur angewendet, wenn includeContent true ist.

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

Eine Taxonomy kann eine Seed-lokale id, locale und translationOf tragen. Terms können diese Eigenschaften ebenfalls tragen. translationOf verweist auf eine andere Seed-lokale ID. Ein Term muss nach dem Term angeordnet sein, den er übersetzt. Taxonomy-Einträge mit demselben name können in beliebiger Reihenfolge erscheinen, weil der Eintrag, der die Struktur der Taxonomy deklariert, vor seinen Übersetzungen angewendet wird.

hierarchical und collections werden von allen Locales einer Taxonomy gemeinsam genutzt, daher kann ein Taxonomy-Eintrag, dessen translationOf auf einen Eintrag mit demselben name zeigt, sie weglassen. Die Apply-Engine folgt translationOf durch Einträge mit demselben name und übernimmt sie vom letzten. Die Validierung warnt, wenn eine Übersetzung andere Werte deklariert als die, die sie übernimmt, oder wenn zwei Einträge, die sie für eine Taxonomy deklarieren, nicht übereinstimmen. Eine vorhandene Taxonomy behält ihre Werte, es sei denn, ein Eintrag ohne translationOf ersetzt sie. Das geschieht mit onConflict: "update" und in jedem Modus, wenn die Locale des Eintrags die unveränderte integrierte category- oder tag-Definition hat, die unter Konfliktverhalten beschrieben ist, oder wenn diese integrierte Definition die einzige der Taxonomy ist. Der Export schreibt sie nur in den Eintrag, auf den Übersetzungen zeigen.

Das parent eines Terms ist der Slug des übergeordneten Terms in derselben Locale. Ein parent an einer nicht hierarchischen Taxonomy erzeugt eine Warnung und wird ignoriert. Ein Term mit translationOf und ohne parent übernimmt das parent des Terms, den er übersetzt.

Bylines

Root-bylines definieren Darstellungs-Credits. Sie sind Beispieldaten und erfordern includeContent: true.

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

Die id ist Seed-lokal und wird von Inhalts-Credits verwendet. Optionale Eigenschaften sind bio, websiteUrl, isGuest und avatar.

Ein Byline-Avatar verweist auf eine Datei, die bereits im konfigurierten Storage existiert:

{
  "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
  }
}

Das Seeden eines Byline-Avatars erstellt oder verwendet eine Medienzeile für den Storage-Schlüssel wieder. Es lädt die Datei weder hoch noch herunter.

Inhalt

content gruppiert Einträge nach Collection-Slug. Jeder Eintrag erfordert eine Seed-lokale id und ein data-Objekt. Routable Collections erfordern außerdem einen nicht leeren slug.

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

Bei einem routable Eintrag ist die Seed-lokale id nicht seine Datenbankidentität. EmDash erstellt eine Datenbank-ID und speichert die Zuordnung für spätere Referenzen. Für einen sluglosen Eintrag in einer Collection mit routable: false verwendet EmDash die Seed-id als gespeicherte ID, sodass das erneute Anwenden idempotent bleibt.

Beim Lesen ist entry.id der Astro-Routenbezeichner und normalerweise der Slug. Die gespeicherte Datenbank-ID ist entry.data.id.

Inhaltsreferenzen

Verwenden Sie einen $ref:-String in data, um eine Seed-lokale Inhalts-ID durch die erstellte Datenbank-ID zu ersetzen:

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

Referenzziele müssen früh genug erscheinen, um in der ID-Zuordnung der Apply-Engine vorhanden zu sein. Ein nicht aufgelöster $ref:-Wert bleibt als ursprünglicher Literal-String bestehen; validateSeed() lehnt ihn nicht ab.

Deklarieren Sie bei einem Reference-Feld die Links vom Elternende seiner Relation aus. Beide Enden sehen dieselbe Menge von Links, ein Feld an der Kind-Collection würde also Links wiederholen, die das Elternende bereits trägt.

Medienreferenzen

Verwenden Sie $media in Inhaltsdaten, um eine URL herunterzuladen, sie mit dem übergebenen Storage-Adapter hochzuladen, eine Medienzeile zu erstellen und das Objekt durch einen Medienfeldwert zu ersetzen:

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

In einem Portable-Text-image-Block oder einem gallery-Bild wird $media in asset zu einer Medienreferenz (_type: "reference", _ref, url, provider), und Alt-Text und Abmessungen des Mediums füllen alt, width und height des Bildes selbst, wenn diese fehlen.

Innerhalb eines Apply-Aufrufs verwenden wiederholte Referenzen auf dieselbe URL den bereits aufgelösten Medienwert wieder. Seed-Medienreferenzen akzeptieren keine lokale Eigenschaft file. mediaBasePath bleibt im öffentlichen Typ SeedApplyOptions erhalten, aber die aktuelle Apply-Engine liest es nicht.

Wird kein Storage-Adapter übergeben, werden $media-Referenzen übersprungen und zu null aufgelöst. Mit skipMediaDownload: true werden sie zu externen Medienwerten, und es ist kein Storage-Adapter erforderlich.

Menüs

Menüs sind strukturelle Daten und werden auch dann angewendet, wenn includeContent false ist:

{
  "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"
        }
      ]
    }
  ]
}

Erlaubte Item-Typen sind custom, page, post, taxonomy und collection. custom erfordert url; page und post erfordern ref. Items können id, translationOf, label, collection, titleAttr, cssClasses, locale, target und verschachtelte children enthalten.

Bei page und post benennt ref eine Seed-Inhalts-ID. Ein fehlendes Ziel erzeugt eine Validierungswarnung und ein Menü-Item ohne aufgelöste Inhaltsreferenz. Vorhandene Menü-Items werden jedes Mal gelöscht und neu erstellt, wenn dieses Menü angewendet wird, unabhängig von onConflict.

Redirects

Redirects erfordern lokale Quell- und Zielpfade:

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

Beide Pfade müssen mit genau einem / beginnen. Protokollrelative URLs, Pfad-Traversal-Segmente und Zeilenumbrüche werden abgelehnt. Erlaubte Statuscodes sind 301, 302, 307 und 308.

Widget-Bereiche

Ein Widget-Bereich enthält content-, menu- oder component-Widgets:

{
  "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 }
        }
      ]
    }
  ]
}

Ein content-Widget speichert Portable Text in content. Ein menu-Widget erfordert menuName. Ein component-Widget erfordert componentId und kann props übergeben. SeedWidget hat keine Eigenschaft settings.

Vorhandene Widgets in einem Bereich werden jedes Mal gelöscht und neu erstellt, wenn der Bereich angewendet wird, unabhängig von onConflict.

Sections

Sections enthalten wiederverwendbaren Portable-Text-Inhalt:

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

Section-Slugs enthalten Kleinbuchstaben, Ziffern und Bindestriche. source ist theme, user oder import; ein Seed setzt es standardmäßig auf theme. Theme-Sections können in der Administration nicht gelöscht werden. Sections sind strukturell und werden auch dann angewendet, wenn includeContent false ist.

Lokalisierung

defaultLocale füllt fehlende Locales für Taxonomies, Terms, Menüs, Menü-Items und Inhalt. Die aktive i18n-Konfiguration der Laufzeit hat Vorrang, sofern vorhanden.

Lokalisierte Taxonomies, Terms, Menüs, Menü-Items und Inhalte verwenden die Seed-lokalen Felder id und translationOf. Platzieren Sie das Quell-Item vor einer Übersetzung, damit die Apply-Engine ihre Übersetzungsgruppe auflösen kann. Ein übersetzter Inhaltseintrag muss locale setzen, und sein translationOf muss einen anderen Eintrag in derselben Collection benennen.

Einen Seed programmatisch anwenden

applySeed() und validateSeed() werden aus emdash/seed exportiert. Der folgende Helfer validiert vor dem Anwenden:

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

Die programmatische Anwendung setzt includeContent standardmäßig auf false. Der Einrichtungsassistent übergibt die Entscheidung des Administrators zu Beispielinhalten. Die CLI emdash seed schließt Inhalt standardmäßig ein, sofern nicht --no-content gesetzt ist.

Konfliktverhalten

onConflict ist keine Transaktionsrichtlinie für den gesamten Seed:

• Collections, Felder, Bylines, Inhalt, Redirects und Sections unterstützen Skip-, Update- und Fehlerverhalten.
• Taxonomy-Definitionen und Terms respektieren den geltenden Konfliktmodus. Die Ausnahme sind die integrierten category- und tag-Definitionen, mit denen jede neue Datenbank beginnt: Bis eine Site sie bearbeitet, ersetzt ein Seed, der sie deklariert, sie in jedem Modus.
• Einstellungen verwenden Konfliktbehandlung pro Schlüssel. skip erstellt fehlende Einstellungen und bewahrt vorhandene Werte. update überschreibt jede gelieferte Einstellung; bei seo und social werden nur die gelieferten Felder überschrieben. error stoppt bei der ersten vorhandenen Einstellung; früher in der Seed-Reihenfolge erstellte Einstellungen bleiben angewendet.
• Vorhandene Menüs behalten ihre Menüzeile, ersetzen aber alle Items.
• Vorhandene Widget-Bereiche behalten ihre Bereichszeile, ersetzen aber alle Widgets.
• Ein Inhaltskonflikt wird nach Collection, Slug und Locale abgeglichen. Ein slugloser Eintrag in einer nicht routable Collection wird nach seiner Seed-ID abgeglichen.

Mit onConflict: "update" werden Inhaltsdaten ersetzt und ihre Byline- und Taxonomy-Zuordnungen an den Seed angeglichen. Testen Sie den Update-Modus an einer Kopie, bevor Sie ihn gegen eine vorhandene Site verwenden.

applySeed() gibt Zähler für Collections, Felder, Taxonomies, Bylines, Menüs, Redirects, Widget-Bereiche, Sections, Einstellungen, Inhalt und Medien zurück.

Validierungsverhalten

validateSeed() gibt { valid, errors, warnings } zurück. applySeed() ruft es auf und wirft Invalid seed file, wenn Fehler vorhanden sind.

Der Validator prüft die strukturellen Regeln, die die Apply-Engine erfordert, einschließlich:

• Version und nicht leeres defaultLocale.
• Die Formen der Container für Collections, Felder, Taxonomies, Terms, Menüs, Widget-Bereiche, Sections, Bylines und Inhalt.
• Erforderliche Namen, Labels, IDs, Slugs und unterstützte Feld- oder Widget-Typen.
• Doppelte Identifikatoren in ihrem jeweiligen Geltungsbereich.
• Indexierbare Feldtypen und admin.listColumns-Referenzen.
• Taxonomy-Eltern, Inhaltsübersetzungen, Byline-Referenzen im Inhalt und Anforderungen an Menü-Items.
• Sichere lokale Redirect-Pfade und Statuscodes.

Einige Bedingungen sind Warnungen statt Fehler. Beispiele sind eine Taxonomy ohne Collections, ein Elternteil an einer flachen Taxonomy oder eine Menü-Inhaltsreferenz, die im Seed fehlt.

Der Validator beweist nicht, dass alle data-Werte ihren Collection-Feldern entsprechen. Er validiert auch nicht tiefgehend die Site-Einstellungen, validation und options von Feldern, beliebige Portable-Text-Blöcke, Props von Component-Widgets, $ref:-Ziele in Inhaltsdaten oder die Verfügbarkeit entfernter $media. Ein gültiger Seed kann trotzdem während der Schema-Erstellung, Inhaltsvalidierung, des Netzwerk-Downloads oder des Storage-Uploads fehlschlagen.

Verwenden Sie die $schema-URL für Editor-Unterstützung und führen Sie den ausführbaren Validator vor dem Anwenden aus:

npx emdash seed seed/seed.json --validate

CLI-Befehle

Wenden Sie einen Seed mit explizitem Konfliktverhalten auf eine lokale SQLite-Datenbank an:

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

Exportieren Sie das aktuelle lokale Modell und den gesamten Inhalt zurück in den Template-Pfad:

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

export-seed arbeitet direkt mit einer lokalen SQLite-Datei. Für eine bereitgestellte D1-Datenbank exportieren Sie sie zuerst in eine lokale Datei. Prüfen Sie exportierte Einstellungen, Inhalt und Medienreferenzen, bevor Sie das Ergebnis committen. Um exportierte Medien auf einer anderen Site importierbar zu machen, übergeben Sie --media-base-url; siehe Medien-URLs.

Nächste Schritte

• Ein Theme erstellen, um einen Seed in einem wiederverwendbaren Astro-Template zu verwenden.
• Schema-Evolution, um das Modell einer vorhandenen bereitgestellten Site zu aktualisieren.
• CLI-Referenz für Datenbank- und Exportoptionen.