Anhur

Anhur

What it is

Anhur turns files in your repo (Markdown, MDX, YAML, JSON) into typed data your app can import, like allPosts and getPost("hello").

At build time it:

1. Reads content from folders you configure
2. Validates each document with Zod schemas you write
3. Optionally compiles MDX/Markdown, copies images, resolves relations
4. Writes modules under .anhur/generated
5. Runs optional integrations (e.g. Orama search index)
6. Lets the app import generated modules as anhur/generated

Vite plugs this into vite dev / vite build via @anhur/vite. The anhur CLI does the same without Vite. Optional folder-based i18n (content/posts/en/…, de/…). Local content as typed code — not a hosted CMS.

More framing: references/why.md

Why you need it

Without something like Anhur, teams usually:

• Hand-parse Markdown in routes (no shared schema, easy to drift)
• Keep content in a CMS (network, auth, preview complexity) when files in git would do
• Copy-paste front matter shapes across pages with no compile-time checks
• Bolt on i18n later as a second system

Anhur is for when content lives in the repo, authors edit files, and the app should treat that content as typed, validated modules — lists, getters, relations, drafts, assets, search — with one config file.

What it is for

Not for (today): remote CMS as the source of truth, Next-only adapters, browser/signed media uploads (runtime media library), non-Zod schema libraries, vector / AI search.

When to use this skill

• Explain Anhur to a user or choose it vs CMS / hand loaders
• Greenfield or migrate a site/app onto Anhur content
• Scaffold or enforce the modular cms/ tree (collections, singletons, enums, objects, views, content)
• Add/change collections, singletons, views/indexes/groups, processors, schemas, or integrations
• Wire folder i18n / mix localized and monolingual sources
• Load or list localized content the Anhur way (getX({ locale, … }), _meta.locale) — not custom filters
• Wire Orama search (orama({…}) in integrations, createSearcher)
• Wire Vite (anhur/generated alias + asset serving) or CI (anhur build)
• Wire remote asset storage (assets({ storage }), files-sdk, CDN base, prune)
• Debug processor/schema mismatches, assets, drafts, localization, views, or search index output

Package map

Rule: every schema helper from an opt-in package needs its processor in defineConfig({ processors }). Missing processor → build fails.

Integrations (search, custom post-codegen work) go in defineConfig({ integrations }), not processors. See references/search.md.

Details: references/packages.md

Integration checklist

Copy and track:

- [ ] Install packages (core + vite and/or opt-ins)
- [ ] Add thin anhur.config.ts (processors / localization / content / views / integrations only)
- [ ] Scaffold cms/: collections/, singletons/, enums/, objects/, views/, content/, content.ts
- [ ] Register processors matching schema helpers
- [ ] One module per collection / singleton; shared enums/objects extracted
- [ ] Author files under cms/content/ (locale folders when using folder i18n)
- [ ] Export `content` tuple from cms/content.ts; wire views via createDerivedHelpers
- [ ] Optional: views: [defineView / defineIndex / defineGroup]
- [ ] Optional: integrations: [orama({…})]
- [ ] Optional: assets({ storage }) for CDN upload (files-sdk peers, enabled in CI/prod only)
- [ ] Vite: plugins: [anhur()] + tsconfig paths for anhur/generated
- [ ] Include .anhur/generated in tsconfig; gitignore .anhur/cache (optional commit generated)
- [ ] Smoke: anhur build OR vite dev; import from anhur/generated (and search index if used)

Project layout (required): references/project-structure.md

Full Vite/tsconfig/CLI steps: references/integration.md

Minimal Vite app

bun add @anhur/core @anhur/vite
# optional:
bun add @anhur/mdx @anhur/markdown @anhur/assets @anhur/orama

vite.config.ts:

import { defineConfig } from "vite";
import anhur from "@anhur/vite";

export default defineConfig({
  plugins: [anhur() /* { configPath: "anhur.config.ts" } */],
});

tsconfig.json paths (Vite plugin aliases at runtime; TS still needs this):

{
  "include": ["**/*.ts", "**/*.tsx", ".anhur/generated"],
  "compilerOptions": {
    "paths": {
      "anhur/generated": ["./.anhur/generated"]
    }
  }
}

Search (@anhur/orama)

Put orama({…}) in integrations. Plain defineConfig({…}) is enough — no defineConfig<typeof content>. defineConfig infers the inline content array and types index / store (do not pass content into orama).

import { defineConfig } from "@anhur/core";
import { orama } from "@anhur/orama";

export default defineConfig({
  content: [posts, pages],
  integrations: [
    orama({
      collections: {
        posts: {
          schema: { title: "string", summary: "string" },
          index: (doc) => ({
            title: doc.title,
            summary: doc.summary ?? "",
          }),
          store: (doc) => ({
            title: doc.title,
            slug: doc.slug,
            href: `/posts/${doc.slug}`,
          }),
        },
      },
    }),
  ],
});

• Rejects unknown collection keys and singleton names at typecheck
• Writes .anhur/generated/search/orama.json (override with directory / filename)
• App: import { createSearcher } from "@anhur/orama/client" then load that JSON (browser or server)

Full options, client usage, custom integrations: references/search.md

Project structure (required)

Do not put collections, singletons, enums, objects, or views inline in anhur.config.ts. Use a modular tree (default root cms/):

anhur.config.ts              # thin wire-up only
cms/
  content.ts                 # `export const content = […] as const`
  collections/               # one defineCollection per file
  singletons/                # one defineSingleton per file
  enums/                     # shared s.enum(…)
  objects/                   # shared s.object(…) fragments
  views/
    helpers.ts               # createDerivedHelpers(content)
    *.ts                     # one defineView / defineIndex / defineGroup each
  content/                   # author MD/MDX/YAML/JSON + assets only
    posts/en/….mdx           # folder i18n when localization is enabled
    authors/….yml            # localized: false → no locale segment

Full rules, localization layouts, checklists, anti-patterns: references/project-structure.md

Config shape

Thin config + modular modules (abbreviated):

// cms/enums/product-status.ts
import { schema as s } from "@anhur/core";
export const productStatus = s.enum(["active", "discontinued"]);

// cms/collections/posts.ts
import { defineCollection, schema as s } from "@anhur/core";
import { schema as a } from "@anhur/assets";
import { schema as m } from "@anhur/mdx";

export const posts = defineCollection({
  name: "posts",
  directory: "cms/content/posts",
  include: "**/*.{md,mdx}",
  generate: { emitIds: true, emitSlugs: true },
  schema: s.object({
    title: s.string(),
    slug: s.slug(),
    featured: s.boolean().optional(),
    draft: s.boolean().optional(),
    cover: a.image().optional(),
    body: m.mdx(),
  }),
  transform: (doc, ctx) => {
    if (doc.draft === true) return ctx.skip("draft");
    return doc;
  },
});

// cms/collections/products.ts — monolingual catalog
import { productStatus } from "../enums/product-status";

export const products = defineCollection({
  name: "products",
  directory: "cms/content/products",
  include: "**/*.json",
  localized: false,
  generate: { split: "list-only", listOmit: [] },
  schema: s.object({
    name: s.string(),
    sku: s.unique(),
    category: s.string(),
    status: productStatus.optional(),
    price: s.string(),
  }),
});

// cms/content.ts
export const content = [posts, products] as const;

// cms/views/helpers.ts
import { createDerivedHelpers } from "@anhur/core";
import { content } from "../content";
export const { defineView, defineGroup, defineIndex } = createDerivedHelpers(content);

// cms/views/featured-posts.ts — import defineView from ./helpers, not @anhur/core
import { posts } from "../collections/posts";
import { defineView } from "./helpers";

export const featuredPosts = defineView({
  name: "featuredPosts",
  from: posts,
  where: (doc): doc is typeof doc & { featured: true } => doc.featured === true,
  generate: { limit: 12 },
});

// anhur.config.ts
import { assets } from "@anhur/assets";
import { defineConfig } from "@anhur/core";
import { mdx } from "@anhur/mdx";
import { orama } from "@anhur/orama";
import { content } from "./cms/content";
import { featuredPosts } from "./cms/views/featured-posts";
import { productBySku } from "./cms/views/product-by-sku";
import { productsByCategory } from "./cms/views/products-by-category";

export default defineConfig({
  localization: {
    strategy: "folder",
    locales: ["en", "de"],
    defaultLocale: "en",
  },
  processors: [mdx({ gfm: true }), assets({ dir: ".anhur/assets", base: "/anhur-assets/" })],
  content,
  views: [featuredPosts, productBySku, productsByCategory],
  integrations: [
    orama({
      collections: {
        posts: {
          schema: { title: "string" },
          index: (doc) => ({ title: doc.title }),
          store: (doc) => ({ slug: doc.slug }),
        },
      },
    }),
  ],
});

Schema helpers, generate splits, hooks: references/schemas.md

Views / indexes / groups: references/views.md

CDN / object storage for assets: references/assets-storage.md

Content layout

Author files live under cms/content/ (or the chosen root’s content/).

Localized (default when localization is set): {directory}/{locale}/…
Example: cms/content/posts/en/hello.mdx, cms/content/posts/de/hello.mdx.

Monolingual: set localized: false (files directly under directory, or singleton filePath).

Mix localized and monolingual sources in one project. defaultLocale must be listed in locales.

Built-in loaders: front-matter MD/MDX, YAML, JSON. Extra loaders via loaders (matched before builtins).

Localization — consuming data

Folder i18n is already baked into generated exports. Use those APIs — do not hand-filter with a custom lang field, re-glob cms/content/, or invent a second content i18n layer.

When localization is set, import the catalog from generated output:

import { type Locale, locales, defaultLocale } from "anhur/generated";
// Locale = "de" | "en"  •  locales / defaultLocale are runtime consts

Rules that bite:

1. _meta.locale is typed as Locale on localized docs — not a schema field you invent.
2. allPosts includes every locale. Always scope lists with _meta.locale (or a view where that checks it).
3. Localized getters require { locale: Locale, … } in .d.ts. Bare getPost("slug") is runtime-only / discouraged.
4. defineIndex({ key: "slug" }) fails if the same slug exists in en and de. Use the getter, or a composite key `${doc._meta.locale}:${doc.slug}`.
5. References resolve same locale first — no custom join for “German author of German post.”

import { type Locale, allPosts, getPost, getSettings, settings } from "anhur/generated";

const locale: Locale = params.locale;
const post = await getPost({ locale, slug: params.slug });
if (!post) throw notFound();

const posts = allPosts.filter((p) => p._meta.locale === locale);

settings; // defaultLocale only
const localizedSettings = await getSettings({ locale });

Full patterns, indexes/views, singletons, anti-patterns: references/localization.md

Generated API (default light split)

When localization is set:

• Locale — "en" \| "de" (sorted union from config)
• locales / defaultLocale — runtime consts (+ .d.ts)

For collection posts:

• allPosts — light list of all locales (default omits body when that field exists); _meta.locale: Locale
• getPost({ locale, id?, slug? }) — full document; locale required when the source is localized
• Optional: PostId, PostSlug when generate.emitIds / emitSlugs

For localized singleton settings:

• settings — defaultLocale document
• settingsAll (default variantsName; overridable) — all locale variants when emitAll
• getSettings({ locale }) — locale: Locale required

From views (list-only — no getters):

import {
  type Locale,
  allPosts,
  getPost,
  productBySku,
  productsByCategory,
  settings,
} from "anhur/generated";

const locale = "en" satisfies Locale;
const post = await getPost({ locale, slug: "hello" });
if (!post) throw notFound(); // or your router’s missing-page helper

const enPosts = allPosts.filter((p) => p._meta.locale === locale);

productBySku["W-100"]?.price;
productsByCategory.find((g) => g.key === "widgets")?.items;

Import id is always anhur/generated (not a relative path).

Monolingual collections (localized: false) keep string id/slug getters (no locale in the typed query).

CLI (no Vite)

bunx anhur build --root .
bunx anhur watch --root .
# --config path/to/anhur.config.ts

React MDX

import { MDXContent } from "@anhur/mdx/react";

export function PostBody({ code }: { code: string }) {
  return <MDXContent code={code} />;
}

code is the compiled string from m.mdx() on the full document (getPost).

Hard rules

1. Modular layout: collections, singletons, enums, objects, and views live under cms/ (or the project’s documented equivalent). anhur.config.ts only wires processors, optional localization, content, views, and integrations. See references/project-structure.md.
2. One concern per file: one defineCollection / defineSingleton / view / enum / object module. Shared closed sets → cms/enums/; reusable objects → cms/objects/. Author files only under cms/content/.
3. Export a single content tuple from cms/content.ts (as const). Bind views with createDerivedHelpers(content) in cms/views/helpers.ts and import defineView / defineIndex / defineGroup from there — not from @anhur/core.
4. Processor + schema field must match (m.mdx ↔ mdx(), a.image ↔ assets(), …).
5. Relative body images/links need assets(); without it they fail the build.
6. Prefer m.mdx() / md.markdown() / s.raw() for bodies — not ad-hoc compile in transform.
7. Drafts: draft: true or ctx.skip(reason) in transform.
8. Search / post-codegen packages use integrations: [orama({…})], not processors or complete: orama(…).
9. Use plain defineConfig({ content, integrations: [orama({…})] }) — no defineConfig<typeof content>, and never pass content into orama.
10. Put defineView / defineIndex / defineGroup in views, never in the content tuple. Multi-collection views require select. Index keys must be unique or the build fails.
11. Prefer defineIndex over filtering a huge list-only collection for detail routes. Prefer generate.compare over string listSort for numeric fields stored as strings.
12. Localization: folder strategy under {directory}/{locale}/… when localization is set; use localized: false per source for monolingual trees. Consume with generated Locale / getX({ locale, … }) / _meta.locale — never custom lang fields, filesystem re-parse, or bare-slug indexes across locales. See references/localization.md.
13. Do not invent a Next adapter, Valibot schemas, or Orama vector/AI search — out of scope. CDN/object upload is supported via assets({ storage }) + files-sdk (gate with enabled, require prefix, prefer a files factory; empty-emit skips prune unless pruneEmpty: true).
14. Package scope @anhur may rename before/after publish; keep config names (anhur.config.ts, .anhur/, anhur/generated) unless the project documents a rename.

Failure modes

See references/pitfalls.md.

Done when

• Layout matches modular cms/ tree (thin config, content.ts, helpers-bound views)
• anhur build or Vite buildStart succeeds
• App imports from anhur/generated typecheck
• Opt-in fields used only with matching processors
• Localized folders match locales / defaultLocale (or localized: false per source)
• App loads locale content via Locale + getters + _meta.locale (no custom lang filters / content re-parse)
• If search is configured: .anhur/generated/search/orama.json exists and createSearcher works in app
• If views are configured: derived exports import and typecheck (allFeatured…, indexes, groups)