Development kit overview

The development kit is everything that lets you work on templates on your own machine: the local preview, validation and tests of the CLI, the testing helpers for Vitest and Jest, and the engine package underneath them. For a guided start, read Templates as code.

Offline and cloud

Layer	Needs an API key	What it does
Offline	No	Compile templates with your data, report diagnostics, hot-reload paginated preview, HTML snapshot tests; fill Word and PowerPoint templates and compare their XML snapshots
Cloud	Yes; a test key is enough and free	The real Chromium render to PDF or image, templates pull and push, CI previews; the PDF of a filled Word or PowerPoint document (Starter plan and above)

The key formfeed login stores is a live key, so its renders count against your plan; for free renders, store a test key with formfeed login --api-key ff_test_… or set FORMFEED_API_KEY. See Install and log in.

The offline layer runs @formfeed/engine, the same package the web editor and the render servers use, so local diagnostics and previews match what the API produces. Only the final print happens in the cloud: running Chromium with the production fonts and settings on every laptop would make local output differ from production in small, confusing ways. The same goes for Word and PowerPoint templates: the CLI fills the document locally and converts it to PDF on the Formfeed servers, with their fonts.

Packages

Package	Use it for
formfeed	The CLI: init, dev, validate, test, render, templates push and more
@formfeed/testing	Matchers and loadTemplate() for Vitest and Jest, for HTML templates
@formfeed/engine	The template engine, for your own tools
@formfeed/devkit	What the CLI and the testing helpers share: reading template folders and project config, rendering locally. Use it when you build your own tooling around template folders.

All four packages need Node.js 22 or later; @formfeed/engine also runs in browsers. @formfeed/devkit works on the folders the project layout describes, for example:

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

const project = findProject(process.cwd()); // the nearest formfeed.json upwards, or null
if (!project) throw new Error('no formfeed.json here or above');
const tpl = readTemplate(project, 'invoice'); // templates/invoice as one object
const { data } = defaultData(tpl); // data/default.json, else the first data set
console.log(diagnose(tpl, data)); // the editor's diagnostics
const { document } = await renderLocal(project, tpl, data, { mode: 'print' }); // the assembled HTML

Its functions throw DevkitError with a code of usage or validation, which the CLI turns into exit codes 2 and 1.

The loop

formfeed dev invoice               # edit files, watch the preview
formfeed validate                  # also in a pre-commit hook
formfeed test                      # HTML snapshots of every data set
formfeed render invoice --out out.pdf
git commit -am "Invoice: add EPC QR code"
git push                           # CI validates, previews and publishes

Planned

Not available yet:

• formfeed dev --local-chromium and formfeed render --local-chromium: an approximate print with a Chromium already installed on your machine, clearly labelled as not byte-identical.
• Pixel snapshots (toMatchRenderSnapshot) next to the HTML snapshots.

Pages

• Project layout: how a template maps to files.
• Dev server: formfeed dev in detail.
• Testing: matchers, snapshots and CI.
• Engine package: the engine API.