cardstack/boxel-skills/boxel-file-def

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 (a photo URL, a cover from Open Library, an avatar from gravatar)?
│   └── → the catalog `ImageSourceField` (or the URL/ImageDef pair): the URL goes
│         in its `url` half, and the slot can switch to a realm file later with no
│         schema change (references/sample-images.md). A link to a non-image file
│         elsewhere is `contains(UrlField)`. Never store `data:`, `blob:`, or
│         base64 in either.
│
├── 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 a realm file, then store only
│         `linksTo(PngDef/ImageDef/FileDef)`. You write them with
│         `await realm.fs.writeBytes(path, base64)` in a `run-realm-code`
│         script (see `source-code-editing`). Card code that makes the bytes
│         at runtime writes them with `WriteBinaryFileCommand`
│         (references/using-filedef-in-cards.md). 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.

The FileDef a file resolves to is also its policy type. A realm policy grants reads of a file's bytes by the FileDef subclass its extension names — .png is a PngDef, which a rule on ImageDef also matches — and an extension no def covers resolves to FileDef itself. So renaming a file changes which grant reaches it. Module source (.ts, .gts, .js, .gjs) is a TsFileDef or GtsFileDef, which only a rule naming one of those reaches: a rule on FileDef never serves code. See `realm-policy-authoring` §5.

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
• references/sample-images.md — Build-time sample images: pick a source by scenario (the user's own, AI-generated with realm.images.generate, a real photo from the Openverse API from a terminal, or a labelled placeholder), then link it without breaking the realm