boardkit-file-format

.boardkit file format: ZIP structure, serialization, versioning, migrations.Use when working on import/export, persistence, or file format changes.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive technical specification and implementation guide for the .boardkit file format. It covers the internal ZIP archive structure, detailed JSON schemas for metadata and document content, and robust protocols for versioning and data migration. By defining strict serialization rules and storage implementations for both Web (IndexedDB) and Desktop (Tauri) environments, it ensures high data integrity, deterministic output, and seamless backward compatibility for developers working on persistence layers.

Use Cases

  • Case 1: Implementing robust import/export functionality for .boardkit files in web or desktop applications, ensuring full compliance with the ZIP and JSON structure.
  • Case 2: Developing automated migration scripts to upgrade legacy document versions (e.g., v0 or v1) to the latest schema without data loss.
  • Case 3: Optimizing data persistence layers using deterministic serialization and atomic write operations to prevent file corruption during save cycles.
  • Case 4: Setting up rigorous file validation pipelines to check size constraints, ZIP integrity, and schema validity before processing user-uploaded content.
nameboardkit-file-format
description|
.boardkit file formatZIP structure, serialization, versioning, migrations.
allowed-toolsRead, Grep, Glob

Boardkit File Format

Structure

.boardkit = ZIP archive containing:

my-board.boardkit (ZIP)
├── package.json     → Metadata
└── board.json       → Document content

package.json

{
  "name": "my-board",
  "version": "1.0.0",
  "boardkit": {
    "formatVersion": 2
  }
}

board.json

{
  "version": 2,
  "meta": {
    "title": "My Board",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-02T00:00:00Z"
  },
  "board": {
    "viewport": { "x": 0, "y": 0, "zoom": 1 },
    "widgets": [...],
    "elements": [...],
    "background": { "type": "dots", "color": "#f5f5f5" }
  },
  "modules": {},
  "dataSharing": {
    "permissions": [],
    "links": []
  }
}

Constraints

Constraint Value
Max file size 50 MB
Compression DEFLATE level 6
Extension .boardkit
JSON encoding UTF-8

Document Versions

Version Changes
v0 Initial: widgets only
v1 Added: elements[], background
v2 Added: dataSharing section

Migration Functions

// packages/core/src/migrations/index.ts
function migrateV0ToV1(doc: V0Document): V1Document {
  return {
    ...doc,
    version: 1,
    board: {
      ...doc.board,
      elements: [],
      background: { type: 'dots', color: '#f5f5f5' }
    }
  }
}

Serialization Rules

  1. Deterministic - Same input = same output

    • Sort object keys alphabetically
    • No random IDs in output
  2. Atomic writes (Desktop)

    • Write to temp file first
    • Rename to final path
  3. Transactions (Web/IndexedDB)

    • Use IDB transactions
    • Rollback on error

Storage Implementations

Web (IndexedDB)

// packages/platform/src/storage/indexeddb.ts
Database: 'boardkit'
Stores: 'documents', 'history'
Autosave: 500ms debounce
History cap: 100 entries

Desktop (Tauri FS)

// apps/desktop/src/composables/usePersistence.ts
Autosave: 1000ms debounce
Atomic writes via temp file

Import Validation

// Required checks on import
1. File size < 50MB
2. Valid ZIP structure
3. package.json exists and valid
4. board.json exists and valid JSON
5. Version supported (migrate if needed)
6. Schema validation

Key Files

Purpose Path
Document types packages/core/src/types/document.ts
Migrations packages/core/src/migrations/index.ts
Web import/export apps/web/src/utils/boardkitFile.ts
Desktop import/export apps/desktop/src/utils/boardkitFile.ts
IndexedDB storage packages/platform/src/storage/indexeddb.ts
Migration tests packages/core/__tests__/migrations.test.ts