Content-types package

What it is

The bridge between the mesh and whatever consumes it. gtmesh types emits a self-contained TypeScript workspace package (default packages/content-types/) that your static-site generator — or any TypeScript consumer — compiles against. It is the content-types package.

Why it matters

The mesh’s contract is its page schemas and its committed graph. Hand-writing types to match them drifts the moment a schema changes. Generating them keeps the consumer honest: the SSG imports the same shapes the engine guarantees, and gtmesh types --check fails CI the instant the committed package and the schemas disagree.

How it works

gtmesh types reads schemas/ and the page types declared in config.page_types, then writes a buildable package containing:

• per-type page interfaces — one TypeScript interface per page type, derived from its schema;
• a PageType union — the closed set of page types, derived from config.page_types;
• the graph-native reader — loadGraph() (the indexed GraphView over graph/{nodes.jsonl,edges.tsv}, with derived roleOf/byRole/entityOf/edgesOf/membersOf accessors — edgesOf(id, type?) is a node’s whole relationship set, both layers, mirroring Page.edges in the engine) and loadManifest() (the projected site.manifest.json link tree). This is the reader — the old row-shaped loadRegistry()/RegistryEntry reader is removed (§6.2); see the crosswalk if your SSG still uses it;
• page-bundle loaders — to load a page’s content/<id>/index.yaml bundle;
• a redirect reader (loadRedirects()) — reads the url/ALIAS_OF graph layer, returns { from, to } to emit 301s. See Redirects;
• an entities/facet reader + mesh-feed helpers — loadEntities / entitiesByFacet, and breadcrumbs / hubMembers / relatedLinks + the pageSummaries card index, so navigation is a call, not a re-implemented lib/;
• named projections — getProjection(name) returns a typed, cached list of schema-shaped cards (label, thumbnail, tags) from a config mapping;
• co-located asset helpers — assetUrl resolves a bare asset filename to a served URL; copyMeshAssets mirrors the files to your public dir;
• config-derived constants (site.ts) — the section list, the per-environment render set, the site base URL, the facet axes, the thumbnail projection, and the asset base, so the SSG reads engine-owned policy instead of re-declaring it.

The package is self-contained, so the consumer depends on it like any workspace package — no reaching into the mesh internals.

Built or source entry points

codegen.exports in gtmesh.config.yaml sets what the package’s entry points name:

source fits a monorepo whose consumers are all bundlers or TypeScript-aware tools. Next needs the package in transpilePackages; Vite, tsx and vitest read it as is. Every consumer’s tsconfig must use "moduleResolution": "bundler", which is what the package’s own tsconfig switches to. Use dist when something runs the package under plain Node or resolves with NodeNext.

codegen:
  exports: source

// next.config.ts
export default { transpilePackages: ["@acme/content-types"] };

Library API

Everything the package exports, grouped by what it reads. For how these compose into a site build, see Build a website.

Pages — load a page’s content bundle

All accept a PageQuery: { status?, graph?, root?, path? }. Pass status: renderableStatuses(env) to list only the pages an environment renders, and graph to reuse an already-loaded GraphView instead of re-reading it.

Feeds — navigation as cards

Traversal over the mesh link tree, returning ready-to-render PageSummary[]. Page identity + status come from the GraphView (pass the loadGraph() handle as the first argument); the up-link/sibling arrays are a site.manifest.json read. Each accepts opts.status (prune to the render set) and opts.thumbnails (fill card images). See Navigation & relationships.

Projections — schema-shaped cards (projections.ts)

Named projections: a page → a shaped list-item whose shape is a schema (card.schema.yaml → the Card type).

getProjection("productCard")({ status: renderableStatuses(env) })  // → Card[]
  .map(c => ({ href: c.slug, label: c.label, img: c.thumbnail, tags: c.tags }));

Summaries — the card index (summary.ts)

The build-once slug → PageSummary projection: a graph-node + bundle-meta join (label, description, optional thumbnail), scanned once and memoised on the GraphView, so labelling related slugs is O(1) instead of re-parsing bundles. Pass the loadGraph() handle as the first argument.

PageSummary = { slug, type, section, entity, title?, navTitle?, description?, label, thumbnail? }. Pass { thumbnails: THUMBNAILS } to populate thumbnail ({ asset, alt?, caption?, ratio? }); asset is the bare co-located filename (resolve content/<slug>/<asset>).

Graph — the graph-native accessor (graph.ts)

loadGraph(opts?) returns an indexed, read-only GraphView over the committed graph (graph/nodes.jsonl + graph/edges.tsv) — parsed and indexed once per build (no per-call re-parse), source-hidden (you never pass arrays around). It’s a generic accessor: it exposes the raw graph — nodes by id/property + the typed edges — and your SSG builds its own domain lists from the edge relationships it knows. The lib re-encodes no config vocabulary (no cluster/facet/topic groupers), so nothing in it can drift from your gtmesh.config.yaml.

Derived accessors (sugar). The mesh’s authority derivations, computed once per view and reused — so you never hand-roll the apex-edge role scan or the pluralised-hub entity trap. Each wraps the same canonical engine derivation, so roles/entities stay in one place.

g.clustersOf(id).industry      →  g.edgesOf(id, "HAS_INDUSTRY").map(e => e.to)   // every value, as node ids
g.topicsOf(id)                 →  g.edgesOf(id, "MEMBER_OF").map(e => e.to)      // the same memberships, as node ids

Edge-type knowledge (HAS_APPLICATION, HAS_COLLECTION, …) is domain-specific and lives in your SSG — which is exactly where it belongs. Each page bundle also carries its stable node id at _brief.id — use it as the lookup key into getById (it survives renames; a better cache key than the slug).

import { loadGraph, loadPageBrief } from "@acme/content-types";
 
const g = loadGraph();
 
// a listing / index page — enumerate by label
const allProducts = g.byLabel("product");                        // every product page
 
// a detail page — build domain lists by the edge types you know
const id = loadPageBrief("/products/alfa-laval-sru")!.id;         // the stable handle
const applications = g.outNodes(id, "HAS_APPLICATION");           // build your own list, by edge type
const collections  = g.outNodes(id, "HAS_COLLECTION");            // …and another — no entities.csv, no array passing

Migrating off the row reader (loadRegistry → loadGraph)

The row-reconstruction reader (RegistryEntry / loadRegistry* and the slug-keyed helpers) is removed in the graph cleanup (§6.2) — running gtmesh types regenerates the package without it. If your SSG still calls it, move each call to its loadGraph() equivalent. The graph is loaded once and indexed, so these are lookups, not array scans:

The RegistryEntry fields that were derived at reconstruction move to the same edge reads — read them off the graph rather than a row:

Redirects need no change: loadRedirects() returns the same { from, to } list from the url/ALIAS_OF graph layer. It is not deprecated.

Entities — the entity table & facets (entities.ts) — deprecated

These deprecated readers reconstruct a slug-keyed table of entity relationships and their config-declared facet columns (taxonomy.facets); the same data now lives on entity nodes in the committed graph, read via loadGraph() above.

Assets — co-located images & documents (assets.ts + site.ts)

Resolve a bare asset filename to a URL, and ship the files. See Assets.

Store — where the loaders read from

Every loader reads the mesh through a mesh store (store.ts, file-store.ts, snapshot.ts). By default that’s the files at root (or $CONTENT_ROOT), exactly as before. Where a site renders without a filesystem, such as an edge worker, build a snapshot of the mesh at build time and serve it from memory. The loaders and queries then run unchanged, and status filtering, roles and links derive the same way.

// build step (Node): write the snapshot the app ships
import { writeFileSync } from "node:fs";
import { snapshotMesh, renderableStatuses } from "@acme/content-types";
writeFileSync("src/generated/mesh.json", JSON.stringify(snapshotMesh({ root: meshDir, status: renderableStatuses(env) })));
 
// app startup (no filesystem): every loader now reads the snapshot
import { setMeshStore, memoryMeshStore, type MeshSnapshot } from "@acme/content-types/memory";
import snapshot from "./generated/mesh.json";
setMeshStore(memoryMeshStore(snapshot as MeshSnapshot));

The store a call reads is opts.store, then the files at opts.root when the call names one (or at an explicit opts.path, for the manifest, organization and redirect readers), then the store set with setMeshStore, then the files at $CONTENT_ROOT (or the cwd). The /memory entry has no files to read, so a loader called there before setMeshStore, or with { root } or { path }, throws an error that says what to change. Call setMeshStore before any loader runs, and leave root and path out of runtime calls.

A snapshot built with status holds only those pages’ bundles, so query it with that same status (the renderable set you render anyway). A query without it still sees every graph node, but the pruned pages have no bundle to read. Each loader caches its result per store and refreshes when the store’s revision() changes. copyMeshAssets copies files, so run it in the build step with { root }; asset bytes ship with the site’s static files. For the Cloudflare recipe, see Deploying on Cloudflare Workers.

Site — config-derived constants (site.ts)

Projected from gtmesh.config.yaml by gtmesh types, so the SSG never re-declares engine policy.

Types

Generated per-schema interfaces (GuidePage, ProductPage, …), the PageType union, GraphNode / GraphEdge / GraphView, Entity, RegistryBrief, Redirect, Status, LoadOptions, MeshStore, MeshSnapshot, PageBundle, SiteSection, and RenderEnv — all re-exported from the package entry. (RegistryEntry / RegistryRow are removed — §6.2.)

Type names: yours take priority

Your schemas’ definitions become types in the same package entry as the engine’s own exports, so a definition can share a name with one of them: a shared section definition generates Section, and one named status generates Status. When that happens:

• your type takes the plain name. import type { Status } from "@acme/content-types" gives the type from your schema;

• the engine’s stays reachable under the Gtmesh namespace. Every engine export is also available as Gtmesh.<Name>, whatever your schemas define:

  import type { Status, Gtmesh } from "@acme/content-types";
  const mine: Status = "open";                // from your schema
  const page: Gtmesh.Status = "published";    // the engine's page status

• gtmesh types warns once per shared name, naming the import that now resolves to your type.

A schema enum takes the name as a value too, so Status.Red works. A definition’s name can’t break the package build. The one reserved name is Gtmesh itself: gtmesh types stops and asks you to rename a definition that would generate it.

Because a new definition can take a name your code already imports, import engine types through the namespace (Gtmesh.Status, Gtmesh.GraphNode) in code that should keep meaning the engine’s type whatever your schemas add later.

Section is the earlier name of SiteSection. It stays available as a deprecated alias of SiteSection until the next major release, or until your schemas define a Section of their own, whichever comes first. Import SiteSection in new code.

Key files & flags

Related

• types — the command in full
• Lifecycle — how pages reach the committed graph the package reads