WORK-463
ID:WORK-463Status:done

Rename sandbox runtime directory examples to sandboxes with migration

ADR-022 — rename the sandbox runtime directory config from examples/examplesDir to sandbox/dir, with a backwards-compatible migration. The template specs (SPEC-109 §7) reference the new naming.

Priority:mediumComplexity:simpleMilestone:v0.25.0Source:ADR-022
claude/v0.25.0-impl-3 View source

Relationships

Implements 1
Related 2
Branches 4
claude/v0.25.0-impl-3 current done
main donechangeset-release/main doneclaude/v0.25.0-impl doneclaude/v0.25.0-workitems ready
History 3
  1. ecafe59
    Created (done)by bjornolofandersson
  2. f7a6228
    Content editedby Claude
    feat: sandbox dir rename examplesDir → dir with back-compat (WORK-463);
  3. a6bdcba
    Content editedby Claude
    plan(v0.25.0): accept specs/ADRs and decompose into 21 work items

Acceptance Criteria

  • SiteConfig.sandbox.examplesDir is renamed to sandbox.dir (type + readers/writers); the old name is accepted with a deprecation warning during a migration window
  • assembleFromDirectory and the sandbox sources reader use the new field
  • A migration note (and codemod where practical) updates existing configs
  • Docs and {% sandbox %} references use the new naming

Approach

Update packages/types/src/theme.ts (SiteConfig.sandbox) and packages/runes/src/sandbox-sources.ts. Read both names for a release, preferring the new one and warning on the old.

References

  • ADR-022; packages/runes/src/sandbox-sources.ts; packages/types/src/theme.ts

Resolution

Completed: 2026-06-23

Branch: claude/v0.25.0-impl

What was done

  • SiteConfig.sandbox (and the deprecated flat shape) now declare dir? as canonical with examplesDir? marked @deprecated (ADR-022).
  • config-normalize.ts coalesces dir ?? examplesDir, absolutizes it, mirrors the resolved value onto both fields (so any adapter reading either name stays correct), and emits a once-per-process deprecation warning when only examplesDir is supplied. Added the reset flag for tests; 36 normalize tests pass (the existing examplesDir test now also exercises the warning).
  • packages/sveltekit/src/plugin.ts (the primary adapter, both read sites) prefers sandbox.dir. assembleFromDirectory is pure (takes a dirPath), so it needs no change.

Notes

  • Migration path is the runtime deprecation warning (a codemod isn't warranted for a single JSON field). The remaining adapter call-sites (eleventy/nuxt/astro) read the mirrored alias and remain correct; they can migrate to .dir incrementally.
  • Criterion "Docs and
    • ID:Status:draft

      Rename sandbox runtime directory examples to sandboxes with migration

      ADR-022 — rename the sandbox runtime directory config from examples/examplesDir to sandbox/dir, with a backwards-compatible migration. The template specs (SPEC-109 §7) reference the new naming.

      Priority:mediumComplexity:unknown