boxel-file-def

name	boxel-file-def
description	Use when adding or working with file-typed fields (FileDef, ImageDef, MarkdownDef, PngDef, CsvFileDef). Activates when a card needs to reference an image, document, or other file asset.
boxel	{"kind":"skill"}

File Definitions (FileDef)

How to use FileDef, ImageDef, MarkdownDef, and related types for file fields in Boxel cards

Decide what to use (start here)

Need to reference an image / document / file asset?
│
├── External URL only (cover from Open Library, avatar from gravatar)?
│   └── → `contains(StringField)` with a `url` field ONLY for small durable
│         `http(s)` URLs. Never store `data:`, `blob:`, or base64 here.
│
├── File lives inside this realm and you want to display it?
│   └── → `linksTo(ImageDef)` for images, `linksTo(MarkdownDef)` for markdown,
│         `linksTo(PngDef)` for explicit PNG, `linksTo(CsvFileDef)` for CSV,
│         `linksTo(FileDef)` for generic.
│
├── File is uploaded by the user via the card editor?
│   └── → `linksTo(ImageDef)` (or correct subtype). The host's edit-mode picker
│         handles upload; the field stores the resulting realm file URL.
│
├── File is generated by AI/API and arrives as a `data:` URI / blob / bytes?
│   └── → Write the bytes to the realm with
│         `@cardstack/boxel-host/tools/write-binary-file`, then store only
│         `linksTo(PngDef/ImageDef/FileDef)`. The data URI can be a transient
│         command input or `@tracked` preview only; never a saved card field.
│
└── Embed the raw bytes in the card JSON (legacy)?
    └── → Forbidden for new work. `Base64ImageField` exists but is deprecated.
          `contains(StringField)` with a base64 data URI is just as bad.
          File explosion + huge JSON. Use `linksTo(ImageDef)` instead.

Never use contains(ImageDef). ImageDef extends FileDef and like CardDef, it has its own identity — it needs linksTo, not contains. This is the same rule as contains(CardDef): forbidden.

Never inline binary. The host rejects large card JSON around 512KB (Card size ... exceeds maximum allowed size (524288 bytes)), and even smaller inline media clogs the indexer and AI context. Store media bytes as files and link them.

Pair with

• boxel — for the surrounding CardDef/FieldDef and linksTo/contains rules.
• source-code-editing — for the actual file edits adding file fields.
• boxel-ui-guidelines — if you also render the file (image preview, document viewer) in a template.

Don't use for

• Embedded base64 image fields (use FileDef subtypes instead — Base64ImageField is deprecated for new cards).
• Generic linksTo to a CardDef. FileDef is specifically for file-backed assets.

---

Sections (load on demand)

• references/filedef-first-class-file-support.md — FileDef — First-Class File Support
• references/type-hierarchy.md — Type Hierarchy
• references/import-paths.md — Import Paths
• references/available-fields.md — Available Fields
• references/using-filedef-in-cards.md — Using FileDef in Cards
• references/rendering-file-fields-in-templates.md — Rendering File Fields in Templates
• references/markdowndef-vs-markdownfield.md — MarkdownDef vs MarkdownField
• references/filedef-vs-base64imagefield.md — FileDef vs Base64ImageField
• references/no-inline-binary.md — Mandatory no-inline-media rule, generated image workflow, and A Million Dreams MP3 FileDef example