Upgrade a catalog from @ocx-sh/catalog 0.5.x to 0.6.0. Version 0.6.0 is a
breaking release. It replaces the VitePress renderer with Astro, so this page
lists every change a corporate mirror or other consumer must act on.
Before you start
Section titled “Before you start”- Read the sixteen notes below. Notes 1, 3, 4, 5, 6 and 7 can stop a build. Note 2 breaks code that imports the removed theme. Notes 8 to 16 change what visitors, hosts and tooling see.
- Run
ocx-catalog buildfrom a clean checkout after you upgrade. Compare the output against your last 0.5.x deploy before you publish. - Keep your 0.5.x
dist/until the new one is verified. A failed 0.6 build leaves the previous output in place.
Release notes
Section titled “Release notes”-
Node 22.13 or later is required. In 0.6.0,
engines.nodeis>=22.13. Thevitepressandvuepeer dependencies are gone. Remove them from yourdevDependenciesand from any install command, because nothing needs installing beside@ocx-sh/catalog.The
bunvariant ofocx-catalog ciprovides Node too, from 0.6.0. On GitHub it addsactions/setup-nodebeforeoven-sh/setup-bun. On GitLab it usesnode:22-alpineand runsnpm install -g bun@1, instead ofoven/bun:1. Re-render withocx-catalog ciand commit the result, orci --checkreports drift. -
@ocx-sh/catalog/themeis removed. The@layer ocxoverride contract, thedata-slothooks and the--ocx-*component hooks go with it, with no replacement. Delete any import of@ocx-sh/catalog/theme. Yourcssfile still wins over the theme, because every theme rule sits in a cascade layer. The build bundles it with the theme’s styles. A relative@importandurl()resolve from the file’s own directory. The output is minified and hashed under_astro/, so the file is no longer served at/<name>.css.Only
:roottoken overrides are expected to survive upgrades, because the theme has no stable selector contract. See Custom stylesheet. -
Two new keys, and some paths change meaning.
basedeploys the site under a sub-path.chromeselectsneutral(the default) or the experimentalocxshell.If your 0.5.x
siteUrlhas a path, that path becomes the defaultbasein 0.6.0. AsiteUrlpath with characters outside letters, digits,.,_and-fails withBASE_INVALID.In 0.6.0,
favicon,docsNav[].linkand anynav[]orfooter.links[]entry that starts with/are relative tobase. Afaviconmay also be an absolutehttp(s)URL, which is used as written. A//hostvalue, a bare file name, ajavascript:value or a path with a dot segment (.,..or%2e) fails withINVALID_TYPE. The dot-segment rule applies to every link.Under
chrome: "ocx",docsNavfails withCHROME_OCX_CONFLICT, likebrand,navandfooter. Seebaseandchrome. -
More names are reserved. A source label or root-source namespace that equals a top-level name the build writes fails with
INDEX_LABEL_RESERVED. The set covers_astro,sitemap-*,robots.txt,favicon*,pagefind, thebrand.logofile name, and every top-levelpublicDirentry. A 0.5.x config that loaded can stop loading, so rename the index or move the namespace. See Reserved names. -
--outmay not overlap an input. The output directory cannot equal or contain any input tree, and cannot sit insidedocsorpublicDir. A violation fails withOUT_DIR_OVERLAPS_INPUTand exit65, and a failed build leaves the previous output untouched. Choose a directory such asdist. See Output-directory safety. -
A public file may not shadow a generated file. Version 0.5.x let the generated file win silently. In 0.6.0 the build fails with exit
65and names the file in two cases.First, a
publicDirfile such as_headerssits at a path the mirror or the build writes. Second,brand.logohas the same file name as a differentpublicDirfile. Rename one of the two, or move one out ofpublicDir. A logo that lives directly inpublicDirand is that very file is not a collision. -
Malformed input fails with exit
65. A docs page whose frontmatter is not valid YAML fails the build. So does a package root whoseowners,sourceorsuperseded_byfield has the wrong type. The message readsmalformed root at <path>and names the source. Fix the file at its source. -
Detail-page and docs URLs end in
/. Every page is a directory with anindex.html. This covers docs pages too, so/docs/privacybecomes/docs/privacy/.Most static hosts redirect the 0.5.x form
/ns/pkgto/ns/pkg/. Check that yours does, and update any hard-coded links.Two build outputs also moved.
/sitemap.xmlis replaced by/sitemap-index.xmlplus/sitemap-0.xml./assets/*is replaced by/_astro/*. The hashed asset names were never meant to be linked from outside. -
catalog.jsonURL fields stay catalog-root-relative. ThelogoUrlandreadmeUrlvalues in/data/catalog/catalog.jsonnever carrybase. A value starts with/p/, never with/catalog/p/. Every reader joinsbaseitself, so a script that fetches those URLs must do the same. See Output layout. -
The palette searches docs by title, heading and excerpt. With a
docsmount, the Mod+K palette lists a “Docs” group below the packages. It matches a page’s title, its first 20 headings and the first 600 characters of its text, not the full text.Sort and view choices live in the URL. The browser also remembers the view, the sort and the install-pin level under the 0.5.x keys. A URL that names a view or sort wins.
-
The docs mount takes plain Markdown, and rewrites its links. VitePress-only syntax is not supported. A
{#id}heading suffix shows as visible text, so drop it. Fenced code blocks are still highlighted. A page without a frontmattertitleis titled from its first#heading, anddescriptionis the page’s meta description. Sidebar order comes from frontmatterorder, and only.mdfiles are mounted as pages. Images and downloads in the tree are copied under<base>docs/.The build rewrites links to pages and files. A relative
.md, extensionless or file link resolves against its own file. A root-relative link gainsbase. A link to something that does not exist fails the build. External links open in a new tab. A link inside raw HTML (<a href>) is not rewritten.docs/index.mdserves/docs/, and<dir>/index.mdserves/docs/<dir>/. See Docs mount. -
A README link to a file the mirror lacks becomes text. A README link survives as an absolute
http(s)URL, amailto:URL or a#fragment. A relative link or image survives when it points at a file the mirror holds. Any other link becomes its text, and any other image is dropped.Fences without a language are highlighted as in 0.5.x.
-
Pages carry a CSP
<meta>tag. Each page declares a Content-Security-Policy. It allows scripts from the page’s own origin plus hashes of the inline scripts the build ships. Yourcssfile is unaffected. An inline script injected by a host proxy is blocked. -
_headersis still emitted, prefixed withbase. It remains a hard deployment precondition on hosts that do not read it. Translate its rules into your host’s own mechanism, and include thebasein each path. Bunny ignores the file. See Hosting and headers. -
The CLI keeps its 0.5.x surface, and large indices may need a heap hint.
ocx-catalog build,devandci, their flags, their exit codes and every multi-index key keep their meaning. In 0.6.0,devruns an Astro server on127.0.0.1.buildalso holdsSIGINTandSIGTERMuntil it has cleaned up. See Signals.At 10,000 packages the CLI process is the largest. Without a cap it peaked at 2.76 to 2.91 GiB RSS, mostly garbage not yet collected. A forced-GC probe held it near 1.15 GiB. The Astro child peaked at 1.0 to 1.16 GiB.
With
NODE_OPTIONS=--max-old-space-size=1792the CLI peaked at 1.65 to 1.69 GiB with no heap error.NODE_OPTIONSreaches both processes, because the child inherits the environment. These runs needed no flag on a host with about 7 GB of RAM or more. Smaller hosts were not tested. If a build dies with a JavaScript heap error, set the flag. -
The documentation site moves to
ocx.sh/apps/catalog/. The docs used to live atocx-sh.github.io/catalog/. That URL serves the last 0.5.x docs until the owner runs theredirect-stubsjob inpages.yml, which replaces it with redirect stubs.A stub exists for each page only. A meta-refresh stub cannot see a
#fragment, so a deep link to a section lands at the top of the new page. Heading ids may also differ after the move. Update bookmarks and links in your own docs. The old-to-new map is indocs/redirects.json. -
Ephemeral tags and pre-release tracks show on the detail page. A tag the index marks
ephemeralcarries a bar, and a pre-release or build-stamped tag is grouped into a track. See Search and versions. -
latestincatalog.jsonskips ephemeral tags. Ephemeral tags are snapshots the index may prune, so none is ever the newest stable version. A package whose newest build was ephemeral reports an olderlatestthan 0.5.x did. Nothing else in the file changes. -
Search ranks by relevance. The grid and the palette score name, keyword, description and namespace matches, require every word to match, and drop results under half the best score. See How search ranks.
-
READMEs and docs code fences have copy buttons. Every fenced block gets a “Copy code” button. A README also offers a provenance menu with Copy digest, Copy URL and Copy fetch command (
curl -sL).
After you upgrade
Section titled “After you upgrade”- Run
ocx-catalog buildand open the output with a static file server. - If you serve under a path prefix, confirm
basematches it. See Hosting and headers. - If
_headersis inert on your host, run the header probe in Hosting and headers. - Read Known limitations for the behaviours that stay deliberate.