Skip to content
ocx
install

Pin Node.js in the repo

A laptop and a CI runner build the same project with Node.js and nobody picked a version: brew installs Node.js 26 (26.13.0), apt on Ubuntu 24.04 installs Node.js 18 (18.19.1), end of life since 2025-04-30. Pin it once in ocx.toml, let ocx.lock record a digest for every platform, and run it with ocx exec.

Duration

Transcript

A laptop and a CI runner build the same project with Node.

Here is how to pin that Node in the repository with OCX.

On the laptop, Homebrew installs Node 26.

The CI runner uses Ubuntu 24.04, whose package gives Node 18.

18 is already past its end of life.

Each machine took what its installer offered, and no one wrote the version down.

In the project directory, ocx init creates ocx.toml.

ocx add then writes one line into it: the tool, its registry and a tag.

24 is a rolling major tag.

It points at the latest Node 24 build.

So the file records the major you want, not the patch.

ocx add also wrote a second file, ocx.lock.

It records every platform the publisher ships, six of them for Node.

Each row is a digest of one exact build, and a digest cannot move like a tag.

The laptop uses its row, and the CI runner uses its own.

ocx exec runs Node from that machine's row, not from wherever the tag points today.

These commands ran on one Linux machine.

The digest ocx add printed is that machine's row.

The Mac and Windows rows came in the same step, with neither machine involved.

The Linux keys also name the C library, glibc.

OCX matches each host to its row, C library included.

A host with no matching row stops with an error naming the missing platform.

Later, Node 24 gets a new patch release.

ocx update asks the registry where each tag points today.

The tag now points at 24.22.2, so the lock moves.

The pin in ocx.toml stays 24.

Only the lock changed, and that diff goes to review.

ocx upgrade moves the tag itself, but it stays within the current major.

Here it moves nothing, and reports that 26 is available.

Moving to 26 takes the major flag, which edits the pin in ocx.toml.

So a new major arrives only when someone asks for it.

Commit both files with the code.

ocx.toml holds the choice.

ocx.lock holds the exact builds.

Every machine on the same commit then gets the same build for its platform.

OCX is still before version 1, so start with one tool in your own repo.

The installer and a first-project guide are at ocx.sh.

Next: a pin edited by hand, and a lock left behind.

Embed this video

HTML

<div style="aspect-ratio:16/9"><iframe src="https://ocx.sh/learn/videos/01-node/embed/" title="Pin Node.js in the repo" loading="lazy" allow="fullscreen" style="width:100%;height:100%;border:0"></iframe></div>

MDX or JSX

<div style={{aspectRatio: '16/9'}}><iframe src="https://ocx.sh/learn/videos/01-node/embed/" title="Pin Node.js in the repo" loading="lazy" allow="fullscreen" style={{width: '100%', height: '100%', border: 0}}></iframe></div>

README Markdown

[![Pin Node.js in the repo](https://ocx.sh/learn/videos/01-node/light/poster.jpg)](https://ocx.sh/learn/videos/01-node/)

Duration

Transcript

This is Rexy. Rexy writes code on a Mac.

Rexy has a problem.

Rexy: I need Node.js.

Tiny arms. Big plans.

Every tool has its own install ritual.

Rexy: Is this where the asteroid comes in?

Rexy: Done! Never again.

Steggo builds the same project in CI. On Ubuntu.

Steggo: I need Node.js too!

Steggo: Build broke! Works on your laptop?

Rexy: I have 26. You have 18. Oh no.

Now two problems.

Bronto, platform team. The head arrives a bit later.

Bronto: I can help. Tools can live in a registry.

Bronto: Any OCI registry. The one you already run.

Rexy: How does a registry help me?

Bronto: Every machine pulls the same version from it.

Bronto: One line: write down the tool.

ocx.toml says which tools the project needs.

Bronto: The file goes in the repo. Like code.

ocx add also wrote ocx.lock with one exact digest per platform.

Laptop or CI: run node through the lock.

Steggo: I remember nothing. Still works!

Pecky: I'm Pecky the dinosaur!

Pecky: And I need Windows!

A new Node.js patch lands. Historically, this is how dinosaurs end.

Bronto: Relax. The pin says 24. Just run ocx update The pin stays 24. ocx update moved the lock to 24.22.2.

Pre-built binaries, pinned, from the registry you already run.

Embed this video

HTML

<div style="aspect-ratio:16/9"><iframe src="https://ocx.sh/learn/videos/01-node/dino/embed/" title="Pin Node.js in the repo" loading="lazy" allow="fullscreen" style="width:100%;height:100%;border:0"></iframe></div>

MDX or JSX

<div style={{aspectRatio: '16/9'}}><iframe src="https://ocx.sh/learn/videos/01-node/dino/embed/" title="Pin Node.js in the repo" loading="lazy" allow="fullscreen" style={{width: '100%', height: '100%', border: 0}}></iframe></div>

README Markdown

[![Pin Node.js in the repo](https://ocx.sh/learn/videos/01-node/dino/poster.jpg)](https://ocx.sh/learn/videos/01-node/#dino)