Package format

Directory layout

site-package/
  site.json
  assets/<exportId>.<ext>
  fonts/<tmpId>__<index>.<ext>

site.json uses the versioned sajt-site envelope. The current version is 1.

References

• Pages use a package-local tmpId.
• Sections point to pageTmpId.
• Assets use exportId matching [A-Za-z0-9_-]+.
• Image fields use { "assetId": "<exportId>", "alt": "..." }.
• Uploaded font files use <font tmpId>__<files index>.<ext>.

The importer creates fresh database ids and remaps every reference. Foreign Convex ids must never appear in a portable package.

Pages and sections

The home page has an empty slug. Section type and content.type must match. variant must be registered for that type. order is optional: omit it and the import assigns valid sort keys in array position. When you do set it, simple sort strings such as a0, a1, and a2 are valid.

Pages and sections accept an optional externalKey — a stable, package-chosen id (for example "home", "home/hero"). Keys enable incremental merge imports into an existing site: matched keys update, new keys insert, and keyless sections are insert-only.

Use SECTION_REGISTRY to inspect types and variants. Use defineSite() for TypeScript autocomplete and section-content checks.

Theme

Themes use constrained tokens for palette, font pair, density, radius, and button style. Raw colors and CSS are not accepted. Start from DEFAULT_THEME.

Assets

Record the real width, height, and MIME type for each file. The server decodes the actual bytes again. Missing, malformed, oversized, or unsafe assets fail closed and are reported by the import summary.

Asset kind accepts image, logo, favicon, og, video, and document. kind: "video" is a self-hosted clip (mp4/webm/mov, optional durationSec) for video sections with provider: "upload" or a hero's bgVideo slot; the import enforces per-plan size/duration caps and storage quota. kind: "document" is a downloadable PDF (the import checks the %PDF- magic bytes) for documents sections.

Fonts

Uploaded font families may declare license: "licensed" (the default when absent) or license: "trial". Trial families render normally in draft and preview, but publishing is blocked until licensed files replace them. Files whose family or file name carries a TRIAL token are auto-flagged as trial on import.

Bundle

site-kit pack creates manifest.json with SHA-256 and byte length for every embedded file. SnabbSajt verifies the manifest before storing any blob.

Compatibility

The v1 object validator is strict. Unknown fields are rejected rather than silently ignored. Pin the SDK tag for reproducible builds and upgrade when a new SnabbSajt field is required.