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 konventionellen 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 eine nicht leere Zeichenkette ohne führende oder nachgestellte Leerzeichen sein.

Settings

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

Der Setup-Assistent lässt den Administrator den geseedeten Titel und die Tagline ersetzen. Der Standard onConflict: "skip" bewahrt diese Werte, wenn der Seed erneut angewendet wird, und füllt alle gelieferten Settings auf, 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 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 zusammenhängende Ganzzahlen ab 1. currentVersion muss eine deklarierte Version benennen. Das Exportieren und erneute Anwenden eines Seeds bewahrt die genauen Versionsnummern und den aktiven Zeiger; EmDash nummeriert sie nicht um.

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

Gespeicherte Blockwerte enthalten _type, _version und _key. Liefern Sie diese Eigenschaften, wenn Seed-Inhalt eine beibehaltene Version anvisiert. Die Runtime weist die aktive Version und einen Key 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 Sidebar-Reihenfolge. SeedField hat keine sortOrder-Eigenschaft. Felder werden in ihrer Array-Reihenfolge 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 leben in der Relation, an die es gebunden ist; siehe Relations.

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 hat.

Feldvalidierung

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

retiredTypes auf einem Blocks-Feld wird serverseitig verwaltet. Das Entfernen eines Slugs aus allowedTypes setzt ihn in den Ruhestand, sodass vorhandene gespeicherte Blöcke gültig bleiben, während neue Blöcke ihn nicht verwenden können.

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

Relations

Eine Relation verbindet zwei Collections und besitzt die Links zwischen ihren Einträgen. Ein Reference-Feld bindet an eine und sieht ihre Links von einem Ende. 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 eine Relation dafür erstellen lassen, was der kürzere Weg für einen Link ist, 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 nimmt.

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 mehr davon ist. Labels und Limits werden aktualisiert, wenn der Seed mit onConflict: "update" angewendet wird.

Taxonomies

Taxonomy-Definitionen identifizieren 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 geordnet sein, den er übersetzt. Taxonomy-Einträge eines name können in beliebiger Reihenfolge erscheinen, weil der Eintrag, der die Struktur der Taxonomy deklariert, vor ihren Übersetzungen angewendet wird.

hierarchical und collections werden von jeder Locale einer Taxonomy geteilt, sodass ein Taxonomy-Eintrag, dessen translationOf auf einen Eintrag mit demselben name zeigt, sie weglassen kann. Die Apply-Engine folgt translationOf durch Einträge mit demselben name und nimmt 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 unbearbeitete integrierte category- oder tag-Definition hat, die in Conflict behavior beschrieben ist, oder wenn diese integrierte Definition die einzige der Taxonomy ist. Der Export schreibt sie nur auf den Eintrag, auf den Übersetzungen zeigen.

Term-parent ist der Slug des Eltern-Terms in derselben Locale. Ein Elternteil auf einer nicht hierarchischen Taxonomy erzeugt eine Warnung und wird ignoriert. Ein Term mit translationOf und ohne parent übernimmt den Elternteil des Terms, den er übersetzt.

Bylines

Root-bylines definieren Präsentations-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 zeigt auf eine Datei, die bereits im konfigurierten Speicher 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
  }
}

Byline-Avatar-Seeding erstellt oder verwendet eine Medienzeile für den Storage-Key wieder. Es lädt die Datei weder hoch noch herunter.

Content

content gruppiert Einträge nach Collection-Slug. Jeder Eintrag erfordert eine seed-lokale id und ein data-Objekt. Routable Collections erfordern auch 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" }
        ]
      }
    ]
  }
}

Für einen 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, damit die erneute Anwendung idempotent bleibt.

Bei Reads ist entry.id der Astro-Routenidentifikator und normalerweise der Slug. Die gespeicherte Datenbank-ID ist entry.data.id.

Inhaltsreferenzen

Verwenden Sie eine $ref:-Zeichenkette 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-Map der Apply-Engine vorhanden zu sein. Ein unaufgelöster $ref:-Wert bleibt als ursprüngliche Literalzeichenkette; validateSeed() lehnt ihn nicht ab.

Für ein Reference-Feld deklarieren Sie die Links vom Elternende seiner Relation. Beide Enden sehen einen Satz von Links, sodass ein Feld auf der Kind-Collection Links wiederholen würde, die das Elternteil bereits trägt.

Medienreferenzen

Verwenden Sie $media in Inhaltsdaten, um eine URL herunterzuladen, sie mit dem gelieferten 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 der Alt-Text und die Dimensionen der Medien füllen die eigenen alt, width und height des Bildes, wenn sie fehlen.

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

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

Menüs

Menüs sind strukturelle Daten und werden auch 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.

Für 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 gelöscht und neu erstellt, wann immer 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 einem / beginnen. Protokollrelative URLs, Path-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. Es gibt keine settings-Eigenschaft auf SeedWidget.

Vorhandene Widgets in einem Bereich werden gelöscht und neu erstellt, wann immer 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 im Admin nicht gelöscht werden. Sections sind strukturell und werden auch angewendet, wenn includeContent false ist.

Lokalisierung

defaultLocale füllt fehlende Locales für Taxonomies, Terms, Menüs, Menüitems und Inhalt. Die aktive Runtime-i18n-Konfiguration hat Vorrang, wenn vorhanden.

Lokalisierte Taxonomies, Terms, Menüs, Menüitems und Inhalt verwenden seed-lokale id- und translationOf-Felder. Platzieren Sie das Quellelement vor einer Übersetzung, damit die Apply-Engine seine Ü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 Helper 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 Setup-Assistent übergibt die Beispieldaten-Wahl des Administrators. Die emdash seed-CLI 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.
• Settings verwenden Konfliktbehandlung pro Schlüssel. skip erstellt fehlende Settings und bewahrt vorhandene Werte. update überschreibt jedes gelieferte Setting. error stoppt beim ersten vorhandenen Setting; früher in der Seed-Reihenfolge erstellte Settings 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, Settings, 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.
• Collection-, Feld-, Taxonomy-, Term-, Menü-, Widget-Bereich-, Section-, Byline- und Inhaltscontainer-Formen.
• Erforderliche Namen, Labels, IDs, Slugs und unterstützte Feld- oder Widget-Typen.
• Doppelte Identifikatoren in ihrem relevanten Umfang.
• Indexierte Feldtypen und admin.listColumns-Referenzen.
• Taxonomy-Eltern, Inhaltsübersetzungen, Inhalts-Byline-Referenzen und Menüitem-Anforderungen.
• Sichere lokale Redirect-Pfade und Statuscodes.

Einige Bedingungen sind Warnungen statt Fehler. Beispiele sind eine Taxonomy ohne Collections, ein Elternteil auf 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 Site-Settings, Feld-validation, Feld-options, beliebige Portable-Text-Blöcke, Component-Widget-Props, $ref:-Ziele in Inhaltsdaten oder die Verfügbarkeit entfernter $media nicht tief. Ein gültiger Seed kann trotzdem während der Schema-Erstellung, Inhaltsvalidierung, Netzwerk-Downloads oder 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 auf eine lokale SQLite-Datenbank mit explizitem Konfliktverhalten an:

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

Exportieren Sie das aktuelle lokale Modell und allen Inhalt zurück zum Template-Pfad:

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

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

Nächste Schritte

• Create a theme, um einen Seed in einem wiederverwendbaren Astro-Template zu verwenden.
• Schema evolution, um das Modell einer vorhandenen bereitgestellten Site zu aktualisieren.
• CLI reference für Datenbank- und Exportoptionen.