archival types

Options

Arguments

Generates TypeScript definitions for this site's object definitions and prints them to stdout.

The output is a self-contained module exporting a single ArchivalObjects interface, describing objects as a consumer of the built site sees them — the same shape a liquid template gets. It declares every type it references, so it can be dropped anywhere with no imports and no dependency on archival.

archival types

// AUTO-GENERATED by archival - do not edit.

/** An uploaded file. `url` is "" until something has been uploaded. */
export interface ArchivalFile {
  display_type: "image" | "video" | "audio" | "upload";
  filename: string;
  sha: string;
  mime: string;
  name?: string;
  description?: string;
  url: string;
}

export interface PostsObject {
  /** `<object name>/<file name>` this object was read from. */
  path: string;
  /** The object's `order`, or null when it is unordered. */
  order: number | null;
  title: string | null;
  hero: ArchivalFile | null;
}

/** Every object in the site, keyed by name. */
export interface ArchivalObjects {
  posts: PostsObject[];
  settings: SettingsObject;
}

A few details worth knowing about the generated types:

• Objects backed by a directory are arrays; objects backed by a single file are not. An object with no files on disk reads as an empty list, so it's typed as one.
• Every field is nullable, since any field may be unset. Child objects default to [] rather than null.
• Only objects read from their own file carry path and order — child objects live inside their parent's file, so they have neither.
• enum fields become string literal unions, oneof fields become tagged unions, date fields are ISO 8601 strings, and meta fields are a recursive JSON type.
• secret fields are included. They're hidden from templates, but anything consuming these types reads the real value. See secret.

This is the same traversal as archival schemas with a different backend, but it describes a different thing: the JSON schema describes stored objects for editor and LLM validation, while these types describe what a consumer of the built site sees — so files carry their resolved url, and top level objects carry the injected path and order.

The command knows nothing about carriers. To wire these types into a carrier's third argument, use npx archival-carrier-types, which runs this command and writes the result next to each carrier — see Carriers.