unify docs

The JavaScript API

Experimental: this API may change or be removed in any release before v1. The command line is the surface unify promises not to break. If you depend on the API, pin unify's version.

The package exports one function, run. It builds the site, the way unify build does, and returns what the build produced as data.

import { run } from "@fwdslsh/unify";

const { status, diagnostics, files, report } =
  await run({ source: "site", baseUrl: "https://example.com/", dryRun: true, audit: true });

for (const d of diagnostics) console.log(d.severity, d.file, d.line, d.message);
console.log(`status ${status}, ${files.size} files`);
console.log(`${report.findings.filter((f) => f.severity === "broken").length} broken findings`);

run(options)

run(options) is unify build with those options, in your process and your working directory. It runs the same code the command runs: unify.yaml is read the same way and the same files are written. It prints nothing; what the command would have printed comes back as data.

Options are the command's flags by their long names in camelCase, and mean what they mean in the CLI reference: --pretty-urls is prettyUrls, --base-url is baseUrl, --dry-run is dryRun. A flag takes true; an option with a value takes a string; exclude takes an array of strings. false and undefined mean the option was not given. There are no options of its own, and an option that belongs to another command (port, template, external, format, ...) is a usage error, never silently ignored.

It resolves to one object, always with these four keys:

Key
status The exit code: 0, or 1 when a problem was found (or, under strict, an advisory; with audit, a broken finding, or any finding under strict).
diagnostics The problems and advisories the build printed, as objects: { severity, file, line?, message, context?, fixes? }, ordered by path, then line. file is relative to the working directory.
files A Map from output path to bytes (a Uint8Array): the site that was built, whether or not it was written — dryRun writes nothing and still returns it. Empty when a problem, or the audit gate, kept the site from being published.
report With audit: true, the document unify audit --format json prints, as an object. Otherwise null; also null when the build stopped before there was a site to evaluate, such as a failing generator.

It rejects in the two cases the command exits without a result:

import { run } from "@fwdslsh/unify";

try {
  await run({ baseUrl: "example.com" });
} catch (error) {
  console.log(error.name, error.message);
}

Worth knowing