API reference

Install the tagged beta, then import from @snabbsajt/site-kit:

npm install github:HH-Studio/Sajtbuilder-SDK#v0.1.0

defineSite(site)

Accepts a SiteDefinition and returns it unchanged. TypeScript ties each section's outer type to the matching discriminated content.type and checks known fields on object literals.

import { DEFAULT_THEME, defineSite } from "@snabbsajt/site-kit";

const site = defineSite({
  format: "sajt-site",
  version: 1,
  exportedAt: new Date().toISOString(),
  site: {
    businessName: "North Studio",
    vertical: "consultant",
    goal: "show_services",
    language: "en",
    theme: DEFAULT_THEME,
    contact: { email: "hello@example.com" },
  },
  folders: [],
  pages: [{ tmpId: "home", slug: "", title: "Home", order: 0, showInNav: true }],
  sections: [{
    pageTmpId: "home",
    type: "hero",
    variant: "minimal",
    order: "a0",
    content: { type: "hero", headline: "A useful headline" },
  }],
  fonts: [],
  assets: [],
});

defineSection(section)

Accepts one TypedSiteKitSection and returns it unchanged. Use it for reusable typed section constants.

createStarterSite(template?)

Returns a valid PortableSiteV1 starter. The template is "nextjs" or "html" and defaults to "nextjs".

validateSitePackage(payload, options?)

Validates unknown input and returns:

type SiteKitReport = {
  ok: boolean;
  issues: Array<{
    level: "error" | "warning";
    path: string;
    message: string;
  }>;
};

Options may provide assetFileNames and fontFileNames as read-only sets. Validation covers the strict v1 envelope, caps, ids, slugs, cross-references, section content, type/content agreement, variants, asset references, and file names. Self-hosted video (kind: "video" assets, provider: "upload", hero.bgVideo) and document/PDF assets are supported; a video section on provider: "upload" must actually carry its clip in video, or validation fails rather than importing a player with nothing in it. The platform enforces per-plan video and storage caps at import time. Parsed JSON and dynamically assembled data always need runtime validation, even when TypeScript types are present.

packSitePackage(input)

Validates and creates a self-contained import bundle.

type PackInput = {
  site: PortableSiteV1;
  assetFiles: Record<string, Uint8Array>;
  fontFiles?: Record<string, Uint8Array>;
  exportedAt?: string;
};

The promise resolves with { zip, manifest, missing }. The safe public packer throws when validation fails, a declared blob is missing, duplicate candidates exist, or the bundle exceeds its total size cap.

Importing a bundle: new site or merge

The platform import functions (importSite for a JSON payload, importSiteBundle for a packed zip) create a new draft website by default. Both also accept two optional arguments for incremental updates:

• mergeIntoWebsiteId — merge the payload into an existing website instead of creating a new one.
• forceKeys — an array of externalKey values whose sections should be updated even when the owner has edited them in the app.

Merge semantics are per externalKey: new keys insert, unchanged keys no-op, keys whose section is untouched since the last import update in place, and owner-edited sections are skipped as conflicts unless their key is in forceKeys. Nothing is ever deleted, and site configuration, theme, and fonts are never touched by a merge. A pre_import restore point is taken before the first write, and the result includes a per-key report of what was added, updated, unchanged, or skipped. Bundle unpacking runs server-side in the node runtime, so the 150 MB bundle size cap is enforced on the actual zip.

Schema and registry exports

• PortableSiteV1, PortableAsset, PortableFont
• SiteDefinition, TypedSiteKitSection, SectionContent, SectionType
• PortableSectionContent, SiteKitSection, PortableValue, ContentOf
• portableSiteV1, PORTABLE_FORMAT, PORTABLE_VERSION
• sectionContent, SECTION_TYPES
• SECTION_REGISTRY, isValidVariant
• DEFAULT_THEME, ThemeTokens
• PORTABLE_CAPS, checkCaps

SECTION_REGISTRY[type] contains labels, usage guidance, variants, default variant/tone, allowed tones, and default content. The full current section-type catalogue is also summarized in the section registry reference.

See the schema reference for every package field and the full section content catalogue.