boxel-file-def

Files (11)

• SKILL.md
• available-fields.md · references/
• filedef-first-class-file-support.md · references/
• filedef-vs-base64imagefield.md · references/
• import-paths.md · references/
• markdowndef-vs-markdownfield.md · references/
• no-inline-binary.md · references/
• rendering-file-fields-in-templates.md · references/
• sample-images.md · references/
• type-hierarchy.md · references/
• using-filedef-in-cards.md · references/

SKILL.md (first lines)

# 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`](../realm-policy-authoring/SKILL.md) §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

From cardstack/boxel-skills, MIT.

More from cardstack/boxel-skills