Boardkit File Format

Documents

boardkit-file-format

Boardkit File Format is an Agent Skill for documents published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/devops/boardkit-file-format-kevinbarfleur-boardkit/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/boardkit-file-format, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

Deterministic - Same input = same output
- Sort object keys alphabetically
- No random IDs in output
Atomic writes (Desktop)
- Write to temp file first
- Rename to final path
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`