What is HyperDown?

• What is HyperDown?
  • Why HyperDown?
  • The core idea: metadata in SQLite, body in globs
  • Architecture: three build steps, two runtime paths
  • Project 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 five minutes

Why HyperDown?

• Real full-text search, zero infrastructure. FTS5 prefix search across titles, descriptions, and bodies — running from a SQLite file that ships inside your build. No Algolia, no Elasticsearch, no managed row sitting idle on your bill.
• Your content stays in git. Articles are just .mdx files in a folder: review them in pull requests, diff them, branch them, revert them — the workflow your team already has.
• Typed end to end, no drift. Frontmatter becomes a generated TypeScript interface, so a renamed field breaks the build, not production.
• A tiny, self-contained database. The FTS index is contentless — it stores tokens and metadata, never the prose — so the .db stays small and travels with your deploy. Nothing to host.
• Agent-ready out of the box. A bundled MCP server lets Claude Code or opencode scaffold content types and write articles for you. (This very post was created that way.)
• One layer, four frameworks. A single bun create @indago/app runs the same content layer on Vike, React Router v7, TanStack Start, or Next.js.

The core idea: metadata in SQLite, body in globs

• Frontmatter metadata (title, tags, date…) is parsed and persisted in SQLite — one .db per content type. This is what search, filters, facets, and sorting run against.
• The MD/MDX body is never stored in SQLite. It is compiled to a React component by @mdx-js/rollup and loaded through a static import.meta.glob map that codegen writes into your app's .hyper-down/ tree.

Architecture: three build steps, two runtime paths

1. Codegen writes idempotently into the app's .hyper-down/ tree: an ambient <Type>Meta interface (types.ts), a lazy <type>Repository proxy (builder.ts — the new is deferred past module evaluation, which dodges a chunk init-order race in bundled SSR), a static eager import.meta.glob map of MDX bodies (modules.ts), and a default.ts barrel exporting contentModules.
2. The writer parses every file's frontmatter through a parallel read/parse/validate pool, then persists serially in a single transaction — emitting one .db per content type: the metadata table, the <type>_tags bridge, and the contentless FTS5 table.
3. On closeBundle, every .db is copied into dist/metadata/ so the built output is self-contained — an SSR deploy reads the databases there without needing the source content/ tree.

• Server (route loaders) — ContentRepository<T>, exported only from @indago/hyper-down/server: search() (FTS5 MATCH + filters + sort + pagination), distinctValues() (facets for filter UIs), and getMetaBySlug() (serializable metadata with locale fallback). The FTS match runs across all locales and maps back to slugs, so "slow" and "lenta" surface the same article, one row per slug in the requested locale. The .db is opened read-only from disk, memoized across requests, with a prepared-statement cache.
• Client (views) — createContentResolver(contentModules[type]) returns getContent(slug, lang), which resolves the lazy MDX component; render it with MdxRender. This path touches no database code, so node:* built-ins never reach the browser bundle.

const [result, tags] = await Promise.all([
  articleRepository.search({
    locale,
    searchQuery,
    filters: activeTag ? { tag: activeTag } : {},
    sort: { sortBy: "date", sortDir: "desc" },
    pagination: { page, pageSize: 6 },
  }),
  articleRepository.distinctValues({ isJson: true, column: "tags", sortByFrequency: true }, locale),
]);

Project layout: what you write, what gets generated

my-app/
├── content/
│   └── article/                HyperDown collection
│       ├── en/hello.mdx        locale folders; slug = filename
│       └── pt-BR/ola.mdx
├── .hyper-down/                generated — DO NOT EDIT
│   ├── content/article/
│   │   ├── types.ts            ambient ArticleMeta interface
│   │   ├── builder.ts          lazy articleRepository (server-only)
│   │   └── modules.ts          static import.meta.glob of MDX bodies
│   └── default.ts              contentModules barrel
├── frontmatter.json            content-type definitions (Front Matter CMS format)
├── hyperdown.config.json       contentDir, sitemap, i18n
└── vite.config.ts              hyperdownMdxPlugin → framework → hyperdownPlugin

The CLI

# Bootstrap
bunx @indago/hyper-down init both

# New content type — `req|opt` suffix is mandatory per field
bunx @indago/hyper-down create-content --name product --folder Products \
  --fields "title:string:req,price:number:opt,status:choice[draft|live]:req"

# New item, then regenerate the databases
bunx @indago/hyper-down create-item --type article --slug hello-world --lang en
bunx @indago/hyper-down gen:db

# CI gate — exits non-zero on the first invalid file
bunx @indago/hyper-down validate both

The MCP server: agents as first-class authors

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

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

The .agents/ pack

• rules/architecture.md — the pipeline invariants: SSR-only, contentless FTS5, lazy repository, plugin ordering, export map.
• rules/configuration.md — hyperdown.config.json + frontmatter.json shapes.
• rules/checks.md — mandatory checks and do-not-edit (generated) files.
• skills/cli.md, skills/add-content-item.md, skills/manage-content-types.md — step-by-step recipes for the common authoring flows.

How it is tested

• The engine itself runs bun test — component tests use happy-dom + Testing Library; the writer, repository, and codegen have unit suites.
• Every generated app ships the same two layers: a Vitest content-integrity test (walks content/, asserts every .mdx has a valid frontmatter title + date in both locales) and a Playwright e2e suite covering articles, recipes, projects, full-text search (a matching query keeps results; a garbage query shows the empty state), i18n, and navigation.
• The scaffold harness (bun run test:templates) packs the engines as tarballs, scaffolds each template into a temp directory, installs, builds, typechecks, and runs unit + e2e — four frameworks against one identical spec set.

The scaffolds: four frameworks, one contract

Start building in five minutes

bun create @indago/app

bunx @indago/hyper-down init both     # config + frontmatter
bunx @indago/hyper-down create-item --type article --slug hello-world --lang en
bunx @indago/hyper-down gen:db        # build the searchable database