Zum Hauptinhalt springen

Dev-Kit im Überblick

Das Dev-Kit umfasst alles, womit Sie auf Ihrem eigenen Rechner an Vorlagen arbeiten: die lokale Vorschau, die Validierung und die Tests der CLI, die Test-Helfer für Vitest und Jest und das Engine-Paket darunter. Für einen geführten Einstieg lesen Sie Vorlagen als Code.

Offline und Cloud​

SchichtBraucht einen API-SchlüsselWas sie tut
OfflineNeinVorlagen mit Ihren Daten kompilieren, Diagnosen melden, paginierte Vorschau mit Hot-Reload, HTML-Snapshot-Tests; Word- und PowerPoint-Vorlagen füllen und ihre XML-Snapshots vergleichen
CloudJa; ein Test-Schlüssel reicht und ist kostenlosDas echte Chromium-Rendering zu PDF oder Bild, templates pull und push, CI-Vorschauen; das PDF eines gefüllten Word- oder PowerPoint-Dokuments (ab dem Starter-Plan)

Der Schlüssel, den formfeed login speichert, ist ein Live-Schlüssel; seine Renderings zählen also gegen Ihren Plan. Für kostenlose Renderings speichern Sie einen Test-Schlüssel mit formfeed login --api-key ff_test_… oder setzen FORMFEED_API_KEY. Siehe Installieren und anmelden.

Die Offline-Schicht nutzt @formfeed/engine, dasselbe Paket, das der Web-Editor und die Render-Server verwenden; lokale Diagnosen und Vorschauen entsprechen also dem, was die API liefert. Nur der finale Druck passiert in der Cloud: Liefe Chromium mit den Produktionsschriften und -einstellungen auf jedem Laptop, würde die lokale Ausgabe in kleinen, verwirrenden Details von der Produktion abweichen. Dasselbe gilt für Word- und PowerPoint-Vorlagen: Die CLI füllt das Dokument lokal und wandelt es auf den Formfeed-Servern mit deren Schriften in PDF um.

Pakete​

PaketWofür Sie es nutzen
formfeedDie CLI: init, dev, validate, test, render, templates push und mehr
@formfeed/testingMatcher und loadTemplate() für Vitest und Jest, für HTML-Vorlagen
@formfeed/engineDie Template-Engine, für Ihre eigenen Tools
@formfeed/devkitWas CLI und Test-Helfer gemeinsam nutzen: Vorlagenordner und Projektkonfiguration lesen, lokal rendern. Nutzen Sie es, wenn Sie eigene Tools rund um Vorlagenordner bauen.

Alle vier Pakete brauchen Node.js 22 oder neuer; @formfeed/engine läuft auch im Browser. @formfeed/devkit arbeitet auf den Ordnern, die die Projektstruktur beschreibt, zum Beispiel:

import {
  findProject,
  readTemplate,
  defaultData,
  diagnose,
  renderLocal,
} from '@formfeed/devkit';

const project = findProject(process.cwd()); // die nächste formfeed.json aufwärts, oder null
if (!project) throw new Error('no formfeed.json here or above');
const tpl = readTemplate(project, 'invoice'); // templates/invoice als ein Objekt
const { data } = defaultData(tpl); // data/default.json, sonst der erste Datensatz
console.log(diagnose(tpl, data)); // die Diagnosen des Editors
const { document } = await renderLocal(project, tpl, data, { mode: 'print' }); // das zusammengesetzte HTML

Seine Funktionen werfen DevkitError mit einem code von usage oder validation, den die CLI in die Exit-Codes 2 und 1 übersetzt.

Der Arbeitszyklus​

formfeed dev invoice               # Dateien bearbeiten, Vorschau beobachten
formfeed validate                  # auch in einem Pre-Commit-Hook
formfeed test                      # HTML-Snapshots aller Datensätze
formfeed render invoice --out out.pdf
git commit -am "Rechnung: EPC-QR-Code ergänzt"
git push                           # CI validiert, rendert Vorschauen und veröffentlicht

Geplant​

Noch nicht verfügbar:

  • formfeed dev --local-chromium und formfeed render --local-chromium: ein näherungsweiser Druck mit einem bereits auf Ihrem Rechner installierten Chromium, deutlich als nicht byteidentisch gekennzeichnet.
  • Pixel-Snapshots (toMatchRenderSnapshot) neben den HTML-Snapshots.

Seiten​