boxel-file-structure

Boxel File Structure Rules

Rules for organizing files in a Boxel workspace when working locally with boxel-cli.

URL Structure

https://[realm-domain]/[username]/[workspace]/[path].[extension]
Example: https://app.boxel.ai/sarah/pet-rescue/animals/dog.gts

File Naming Conventions

Type	Convention	Example
Card definitions	kebab-case.gts	blog-post.gts, grammy-award.gts
Instance directories	PascalCase/	BlogPost/, GrammyAward/
Instance files	kebab-case.json	my-first-post.json

Directory Structure

workspace/
├── realm.json            # Workspace config (RealmConfig card)
├── index.json            # The workspace's default index card
├── blog-post.gts         # Card definition (kebab-case)
├── BlogPost/             # Instance directory (PascalCase)
│   ├── my-first-post.json
│   └── another-post.json
├── author.gts
└── Author/
    └── jane-doe.json

A new workspace is seeded with exactly two files, realm.json and index.json; everything else is yours. index.json adopts Workspace from @cardstack/base/workspace (workspace.gts), which gives the workspace its Home, Library, and Activity views. Replace that adoption to put your own card on the workspace root instead.

Some workspaces adopt CardsGrid as their root card, and some also carry a separate cards-grid.json instance at the root. Both shapes are supported — CardsGrid remains available — so treat either as valid unless you're deliberately migrating.

Module Paths in JSON (CRITICAL)

The adoptsFrom.module path is relative to the JSON file location.

✅ Correct: Instance in subdirectory

grammy-award.gts          # Definition at root
GrammyAward/              # Instances in PascalCase directory
└── record-of-the-year.json

In GrammyAward/record-of-the-year.json:

{
  "meta": {
    "adoptsFrom": {
      "module": "../grammy-award",  // ← Go UP to parent, then to file
      "name": "GrammyAward"
    }
  }
}