Skip to content
ocx
install

Quickstart

Get a running catalog site from an existing OCX index in four steps: install, configure, build, serve the output.

  • Node.js >=22.13 (package.json’s engines.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:

Terminal window
npm install --save-dev @ocx-sh/catalog

@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].path points at a local directory holding your index’s wire tree (config.json, c/index.json, p/**), relative to this config file.
  • root: true marks this source as the catalog’s primary index — see Configure sources for what that flag does across more than one source.
Terminal window
npx ocx-catalog build --config ./catalog.config.json --out ./dist

Both 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 dist with any static file server. This one needs only Python 3:

Terminal window
python3 -m http.server --directory dist 8080

Open 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.

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.

  • 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.

  • Configure sources — point at more than one index, or a url/git source instead of path.
  • Preview locally — iterate without a full build.
  • Before picking a host, read Known limitations. _headers is a hard deployment precondition, and not every static host honors it.
  • Serving under a path prefix such as /my-index/? Set base.