What is HyperJson?

• What is HyperJson?
  • The problem it solves
  • Why HyperJson?
  • Architecture: validate, generate, import
  • Content layout: what you write, what gets generated
  • The CLI
  • The MCP server: agents as first-class authors
  • The .agents/ pack
  • How it is tested
  • The scaffolds: four frameworks, one contract
  • Start building in minutes

The problem it solves

Why HyperJson?

• Invalid content can't ship. Ajv validates every file in strict mode on buildStart; one wrong type or stray key exits the build non-zero. Your CI is your CMS.
• Types you never write or maintain. The schema generates the TypeScript, so import data from "@content/projects/en/projects.json" is fully typed with zero casting — and it can't drift, because there is nothing hand-written to drift.
• No backend, no runtime. Validation and codegen run at build time; what ships is plain typed JSON imports — nothing to deploy, nothing to call, nothing to pay for.
• Headless hooks, your UI. useFilter, useSearch, useSort, usePaginate, and useComposed shape the data in React without imposing a single component.
• Schema-driven by agents. A bundled MCP server lets Claude Code or opencode create a content type and fill its data files, schema-checked at every step.

Architecture: validate, generate, import

1. Validation. Every .json file is checked against the schema.json sitting in its category folder, using Ajv (+ formats) in strict mode by default — unknown properties are rejected. With failOnError (the default), a single invalid file exits the build non-zero. The scan covers locale subfolders (en/, pt-BR/) and JSON files at the category root.
2. Codegen. HyperJsonCodegen compiles each schema through the in-process json-schema-to-typescript API — no subprocess per schema — inside a bounded parallel pool. The concurrency resolves in priority order: explicit option → HYPERJSON_CONCURRENCY env var → cpus - 1 (so a build stays responsive). It writes only into the consuming app's .hyper-json/ tree, never into the installed package. Ambient module declarations are emitted last, after all per-schema types settle, because they aggregate every content file.
3. Typed imports. The generated declare module blocks are keyed off your @content/* path alias (read from tsconfig.json#paths), so import data from "@content/music/en/playlists.json" yields a fully-typed value with zero casting. Each schema's title becomes the generated type name.

const { paginated } = useComposed(playlists, {
  filters: [{ key: "genre", value: selectedGenre }], // "All"/undefined ⇒ skipped
  searchQuery,
  searchFields: ["title", "artist"],
  sort: { key: "title", dir: "asc" },
  page,
  perPage: 12,
});

Content layout: what you write, what gets generated

my-app/
├── content/
│   └── projects/
│       ├── schema.json          JSON Schema — the single source of truth
│       ├── en/projects.json
│       └── pt-BR/projects.json
├── .hyper-json/                 generated — DO NOT EDIT
│   └── content/
│       ├── projects/types.ts    type generated from schema.title
│       └── generated.d.ts       ambient @content/**/*.json declarations
├── hyperjson.config.json        contentDir + validation flags
└── tsconfig.json                paths: { "@content/*": ["./content/*"] }

{
  "$schema": "./node_modules/@indago/hyper-json/schemas/hyperjson.config.schema.json",
  "contentDir": "content",
  "validation": { "strict": true, "failOnError": true },
}

The CLI

bunx @indago/hyper-json init

# Semicolon-separated fields; third segment `required` marks a field required
bunx @indago/hyper-json create-content-type \
  --name projects \
  --locales "en,pt-BR" \
  --fields "id:string:required;name:string:required;url:string"

# CI gate — exits non-zero when any file fails
bunx @indago/hyper-json validate

# Regenerate types (bound the pool if you need to)
HYPERJSON_CONCURRENCY=2 bunx @indago/hyper-json generate

The MCP server: agents as first-class authors

{
  "mcpServers": {
    "hyperjson": { "command": "bunx", "args": ["hyperjson-mcp"] }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hyperjson": { "type": "local", "command": ["bunx", "hyperjson-mcp"], "enabled": true }
  }
}

The .agents/ pack

• rules/architecture.md — validation, codegen, virtual config, hooks.
• rules/configuration.md — hyperjson.config.json + schema.json shapes.
• rules/checks.md — mandatory checks and do-not-edit (generated) files.
• skills/cli.md, skills/add-content-type.md, skills/change-schema.md — how to add a type and how to evolve an existing schema safely.

How it is tested

• The engine itself runs bun test over validation, codegen, and the hooks.
• Every generated app asserts the projects collection in its Vitest content-integrity test (the JSON parses, the wrapper array is non-empty, fields are typed) and exercises /projects in the shared Playwright e2e suite.
• The scaffold harness (bun run test:templates) packs the engine as a tarball, scaffolds all four templates, and runs build + typecheck + unit + e2e against each — so an invalid schema or a codegen regression fails four ways before it ships.

The scaffolds: four frameworks, one contract

Start building in minutes

bun create @indago/app

bunx @indago/hyper-json init
bunx @indago/hyper-json create-content-type --name projects --locales "en,pt-BR" \
  --fields "id:string:required;name:string:required;url:string"
bunx @indago/hyper-json generate     # types from your schemas