Programmatic API

The public package root exposes the same operations the syncpress executable uses. Import these functions from @mit-sdg/syncpress.

The package is ESM-only. Import it from an ES module; CommonJS require() is not supported.

import { buildSite } from "@mit-sdg/syncpress";

const result = await buildSite("./site");
console.log(`${result.written} files written`);

All functions are asynchronous. A rejected promise reports invalid project boundaries, invalid configuration, build failures, filesystem failures, or invalid CLI arguments as applicable. The package does not define public error subclasses or stable machine-readable error codes for these rejections.

buildSite and inspectSite each create and discard a fresh strict batch application. watchSite and serveSite retain controller applications until close(), but the initial build and every rebuild still use fresh batch applications. Applications and gateway handles are internal and are not part of the public API.

buildSite

function buildSite(
  projectDirectory?: string,
  destination?: string,
): Promise<BuildResult>;

projectDirectory defaults to the current directory. An omitted destination uses paths.output from site.yaml, or dist when that setting is absent. A relative destination is resolved from the project directory.

buildSite stages the complete project, runs a strict build, and reconciles the output only after the build reaches a clean terminal state. The result contains route-claim and input counts; written, replaced, retained, and removed file counts; the assessed site policy; the output directory it published into, with symbolic links resolved; and diagnostics. The pages field counts all route claims: authored pages, redirects, and generated pagination routes. The fresh batch application is not reused for a later build.

inspectSite

function inspectSite(
  projectDirectory: string,
  target: string,
): Promise<InspectionResult>;

target is a canonical route beginning with / or a content-root-relative page path. Inspection builds an isolated application model and returns source, route, template, data provenance, collection membership, dependency, output, claim, and diagnostic data for the selected page. The configured destination remains unchanged. The promise rejects when no routed page or content source matches target. Its isolated batch application is discarded after the inspection result or failure summary is formed.

watchSite

function watchSite(
  projectDirectory?: string,
  destination?: string,
  options?: {
    onBuild?: (result: BuildResult, outputDirectory: string) => void;
    onError?: (error: unknown) => void;
  },
): Promise<SiteWatcher>;

watchSite performs the initial strict build before resolving. It then watches the project recursively and invokes onBuild after each successful build with the result and canonical output directory. The watcher controller is retained, but every rebuild creates a fresh strict batch application. Later build and watcher failures are passed to onError when that callback is provided. A failed rebuild leaves the last reconciled output in place and ends the attendance loop; call close() to release the watcher resource.

Call await watcher.close() to stop watching and release the watcher. Repeated close() calls have no further effect.

serveSite

function serveSite(
  projectDirectory?: string,
  destination?: string,
  options?: {
    host?: string;
    port?: number;
    onError?: (error: unknown) => void;
  },
): Promise<DevelopmentServer>;

serveSite starts watch mode and an HTTP development server for the reconciled output. The default host is 127.0.0.1 and the default port is 3000. The resolved object reports the actual host and port and provides close(). The server and watcher are retained controllers; their builds remain fresh batches. Call await server.close() to stop the watcher, close live-reload clients, and close the HTTP server.

Use this server only for local development. It serves the output root directly. See development mode for base-path behavior, request mapping, and live reload.

runCli

function runCli(args?: string[]): Promise<void>;

runCli parses the supplied argument array. When args is omitted, it uses the process arguments after the executable and script names. The function writes command output to the process standard streams and rejects on invalid usage or command failure. The installed executable catches that rejection and sets a nonzero process exit status; a program that calls runCli directly is responsible for handling the rejection.

Public types

The package root exports BuildResult, InspectionResult, Diagnostic, SitePolicy, SiteWatcher, DevelopmentServer, and FeedPolicy. These types describe the values and handles returned by the public functions.