Get a running catalog site from an existing OCX index in four steps: install, configure, build, serve the output.
Prerequisites
Section titled “Prerequisites”- Node.js
>=22.13(package.json’sengines.node). - An existing OCX index to point at: a local directory, an HTTPS endpoint, or a git repository.
Install the package. It bundles its renderer, so there is nothing else to install:
npm install --save-dev @ocx-sh/catalogbun add --dev @ocx-sh/catalogWrite a config
Section titled “Write a config”@ocx-sh/catalog reads a catalog.config.json. Two keys are required — sources (at least one entry) and brand (at least title):
{ "$schema": "https://cdn.jsdelivr.net/npm/@ocx-sh/catalog/src/config/schema/catalog.config.schema.json", "sources": [ { "path": "./index", "root": true } ], "brand": { "title": "My Catalog" }}sources[0].pathpoints at a local directory holding your index’s wire tree (config.json,c/index.json,p/**), relative to this config file.root: truemarks this source as the catalog’s primary index — see Configure sources for what that flag does across more than one source.
npx ocx-catalog build --config ./catalog.config.json --out ./distBoth flags have defaults, so a bare npx ocx-catalog build works too: --config defaults to ./catalog.config.json in the current directory, and --out defaults to ./dist.
Serve the output
Section titled “Serve the output”Serve dist with any static file server. This one needs only Python 3:
python3 -m http.server --directory dist 8080Open http://127.0.0.1:8080/. This works while base is /, which is the
default. A site built with another base, such as /my-index/, links every
asset under that prefix, so a server that serves dist at its root shows
broken pages. Preview that site with npx ocx-catalog dev, which serves under
base, or mount dist at the prefix on your own server. A plain file server
also ignores _headers.
What root: true does
Section titled “What root: true does”Every configured source’s wire tree is always mirrored, byte-verbatim, under dist/index/<label>/. Setting root: true on one source additionally copies that same tree to dist/ itself — the site-root placement index.ocx.sh’s own self-mirror deployment expects. At most one source may set root: true; a second one fails the build.
What you get in dist/
Section titled “What you get in dist/”- The rendered static site: a package grid, per-package detail pages, and (if configured) a docs mount. Each page is a directory with an
index.html, so URLs end in/. dist/_astro/— the hashed JS and CSS bundles.dist/data/catalog/catalog.json— the merged view-model the grid and search read. Search ranks by relevance; see Search and versions.dist/_headers— the Cloudflare Pages/Netlify header rules that sandbox mirrored, untrusted wire content.
Full file-by-file layout: Output layout.
Next steps
Section titled “Next steps”- Configure sources — point at more than one index, or a
url/gitsource instead ofpath. - Preview locally — iterate without a full build.
- Before picking a host, read Known limitations.
_headersis a hard deployment precondition, and not every static host honors it. - Serving under a path prefix such as
/my-index/? Setbase.