A central glowing Halodoc code package linked by neon lines to a row of browser windows — one dependency policy feeding many web frontends.

One Catalog, Many Frontends: Centralizing Dependency Management with pnpm Config Dependencies

Angular Nov 20, 2026

Halodoc's mission is to simplify healthcare for millions of people across Indonesia, and our software only helps if it ships quickly and runs safely. It takes a lot of frontends to do that, and a surprising amount of "quickly and safely" comes down to a boring question: are they all on the same known-good, up-to-date dependency versions?

If you maintain more than one frontend, you've probably made the same dependency bump, by hand, in a dozen repos that each deploy on their own schedule.

Halodoc's web presence isn't one application. It's dozens of Angular apps, micro-frontends, host shells and shared component libraries, each built and deployed on its own. Every one has its own Git repository, its own package.json and its own release schedule. We set it up that way on purpose, so teams can ship without waiting on each other. The cost is version drift, and it builds up over the years.

Across those repositories, the framework spans several major versions at once, and TypeScript spans even more. (That's why, as you'll see later, the policy groups its catalog by framework major instead of assuming one version per dependency.) Shared libraries drift the same way. A reactive library, a PDF renderer, a user-agent parser: each one sat at a slightly different version in almost every repo. Nobody could answer "what version of X does the whole fleet use?", let alone change it.

So when a CVE lands in one of those shared dependencies, "patch it everywhere" means opening, reviewing and merging the same change in repo after repo, then hoping you didn't miss one. Java teams solved this long ago with a parent pom.xml: you set a version in one place and every service inherits it. JavaScript never had a real equivalent.

So we built one: a central dependency-version policy for the web fleet. It's a single, versioned source of truth for which version of each governed dependency every app should use. A CI gate enforces it, but it doesn't fail pipelines over version lag that doesn't affect them. Instead, it tells each repo exactly when it needs to adopt a change. This post walks through how it works, and the content-aware gate that makes it safe to roll out.

Why Independent Frontend Repos Make This Hard

A monorepo would make this simpler: one lockfile, one version of everything, one pull request to change it. But we never wanted to merge these repos. They're separate websites and apps with different owners, release schedules and purposes, and keeping them independent is a choice, not a problem to fix. We needed one source of truth for shared dependency versions without squashing everything into one repo.

We looked at the obvious options first, and each one fell short for a specific reason:

  • A shared package.json or preset that every repo copies. It drifts as soon as someone edits one copy, and nothing keeps the copies in sync.
  • Renovate alone. We looked at this first. Renovate is a general dependency-update bot: it opens MRs to bump each repo's dependencies, by default to the latest version. Even with a shared preset, two things pull repos apart. Its vulnerability fixes override the preset's pins: when a dependency has a CVE, Renovate moves the repo to a version without the vulnerability, which isn't necessarily the version the preset names. And each repo moves only when its team merges those MRs, so the fleet converges only as fast as its slowest team. Renovate alone can't hold every repo to one source of truth. Pointing Renovate at the policy itself would fit well: it could watch the versions the policy names and raise one MR against the policy when one gets a security fix. Our security team already runs a pipeline that does that detection, so we didn't add Renovate on top.
  • A hard pin that fails CI on any drift. Publish the canonical versions and fail any build that doesn't match. There's no built-in way to adopt a new version, so developers have to edit each package.json by hand to match the pin. It breaks every repo in the fleet the moment the canonical version moves ahead of them, so engineers learn to turn the check off.

So the system has to tell the difference between a version that's just behind and one that's actually wrong. A gate that treats them the same fails builds that people then learn to ignore.

Choosing the Approach

Our first proof of concept leaned on syncpack as an enforcement linter, with a hand-edited versions.json generating its config. It worked, and it taught us a lot about the problem, but there was a catch: enforcement landed on the developer. When a dependency drifted, someone had to run a custom script that read the central config and rewrote their repo's package.json to match, then commit the diff. That left the developer unsure whether the change was even correct. Worse, by committing it, they looked like the author and owner of a version bump they never actually decided.

So we moved the fleet to pnpm 10, specifically for two features that opened up a much cleaner design: catalogs (available since pnpm 9.5) and config dependencies (new in pnpm 10).

Every onboarded repo pins its exact pnpm version in package.json (packageManager), with a pnpm 10.4 floor. CI installs that exact version before each build, and an older pnpm on a laptop is refused outright rather than silently skipping the config dependency. Because the version lives in package.json, moving a repo to pnpm 10 was mostly a one-line change plus a regenerated lockfile, and it didn't surface any errors.

A pnpm catalog lets a repository replace a hard-coded version with a pointer. The actual version is defined centrally instead of being written into each repo:

// package.json in a consuming app
{
  "dependencies": {
    "lodash": "catalog:",
    "pdfjs-dist": "catalog:",
    "ngx-mask": "catalog:ng<major>",
    "ngx-infinite-scroll": "catalog:ng<major>"
  }
}

catalog: resolves to a version defined once, centrally. The repo stops saying which version of lodash it wants and just says it wants the fleet's lodash.

A pnpm config dependency is the other half. It's a package, pinned by exact version and integrity hash, that pnpm installs before resolving anything else, and it's allowed to provide a pnpmfile.cjs hook. That was the delivery mechanism we'd been missing: we could ship the catalog contents as a package.

Put together, the design has three parts:

  1. A policy package, @org/dep-version-policy, that holds the canonical versions and injects them as catalogs. It's the single source of truth, and it has a version number and a hash.
  2. A content-aware CI gate in our shared CI pipeline library. It enforces the policy across the fleet and tells each repo when it has to adopt a change.
  3. A publish cycle that versions and ships the policy package itself, driven by conventional commits.

How It Works

One edit to the policy reaches every repo that uses it: a version is bumped in the policy (for a security fix, a new feature or an Angular upgrade), published as a hashed package, every repo pins it, and each repo's CI gate decides whether to adopt the change.
One edit reaches every repo that uses it. Someone bumps a version once (to patch a CVE, pick up a new feature or move to a newer Angular), it ships as a hashed package, and each repo's CI gate decides whether that repo has to adopt it. A flagged repo repins to adopt the change (dashed loop).

The Policy Package

The whole policy lives in one file, policy.json, in one repository. It's the only file anyone edits by hand:

// policy.json — the single source of truth, edited only here (entries below are illustrative)
{
  "catalog": {
    "lodash": "<version>",
    "eslint": "<version>",
    "husky": "<version>",
    "pdfjs-dist": "<version>",
    "ua-parser-js": "<version>"
  },
  "catalogs": {
    "ng<major>": {
      "ngx-mask": "<version>",
      "ngx-infinite-scroll": "<version>"
    },
    "ng<older-major>": {
      "ngx-mask": "<version>",
      "ngx-infinite-scroll": "<version>"
    }
  },
  "singletonOverrides": {
    "global": ["ua-parser-js"],   // names only; versions come from "catalog"
    "perCluster": ["ngx-mask"]    // names only; versions come from the repo's own ng<major> catalog
  },
  "exceptionCatalogs": {
    "<exception-name>": {
      "reason": "<why these repos need to diverge>",
      "repos": ["<repo>"],
      "deps": {
        "ngx-mask": "<version>"
      }
    }
  }
}

The catalog block is global: dependencies that use the same version across the whole fleet. The catalogs block holds one cluster per Angular major the fleet runs. singletonOverrides names the dependencies that must resolve to one version across the whole dependency graph; more on that below. exceptionCatalogs is the escape hatch. If a repo genuinely needs to diverge for a while, the exception is recorded in the policy with a reason, the repos allowed to use it and an intended end date, instead of drifting silently inside that repo. Only the listed repos can use it; the end date isn't enforced automatically yet.

Changes to policy.json go through a merge request on the policy repo, reviewed by our web core and security teams, and only the repo's release pipeline can publish the package. A team that needs a new dependency governed, or a version the policy doesn't carry yet, opens the same kind of merge request.

One global value doesn't fit everything. Some dependencies, like lodash, eslint or a PDF renderer, have one sensible version for the whole fleet. Others follow the framework: the right version of an Angular-coupled library for one Angular major isn't the right one for the next. Forcing one number on both would force a framework migration, and a version policy should never sneak in an unrelated, risky change like that. So the policy is clustered: a global catalog for dependencies that don't care about the framework version, plus a named catalog per Angular major. A repo picks its cluster with a pointer like catalog:ng<major>.

The package is installed by hash, not by tag. In the consuming repo's pnpm-workspace.yaml, the policy is a config dependency pinned to an exact version and sha512 integrity:

# pnpm-workspace.yaml in a consuming app
configDependencies:
  "@org/dep-version-policy": "<version>+sha512-<integrity-hash>"

pnpm installs it first and runs its pnpmfile.cjs. That file's updateConfig hook injects the catalog definitions into pnpm's config.catalogs, so every repo resolves its catalog: pointers against the policy's versions without writing a single one by hand. The repo never copies the version table. It references it, and the hash guarantees it got exactly the bytes we published.

The same pnpmfile.cjs also catches mistakes. Its readPackage hook reads the repo's Angular major from its own @angular/core, and fails the install if the repo points at another major's cluster catalog. So a mismatch shows up locally, before CI even runs.

// pnpmfile.cjs inside the policy package (simplified)
const policy = require('./policy.json');

module.exports = {
  hooks: {
    // Before resolution: hand pnpm the policy's catalogs.
    updateConfig(config) {
      config.catalogs = {
        ...config.catalogs,
        default: policy.catalog,   // "catalog:"
        ...policy.catalogs,        // "catalog:ng21", "catalog:ng22", ...
      };
      return config;
    },
    // For each package: only the repo's own Angular cluster is allowed.
    readPackage(pkg) {
      const own = `ng${currentAngularMajor()}`; // from the repo's @angular/core
      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
      for (const spec of Object.values(deps)) {
        const cluster = /^catalog:(ng\d+)$/.exec(spec)?.[1];
        if (cluster && cluster !== own) {
          throw new Error(`cluster mismatch: repo is ${own}, uses ${cluster}`);
        }
      }
      return pkg;
    },
  },
};

Moving up a cluster is one merge request: the repo runs its Angular upgrade and switches its catalog:ng<major> pointers together. The hook checks the result, so a half-done move, with Angular bumped but pointers not (or the reverse), fails the install.

A few packages need an extra guarantee: a single version across the whole dependency graph, including copies pulled in indirectly, not just what a repo declares in its own package.json. The policy handles this with a short, names-only list, singletonOverrides, that the hook applies as pnpm overrides, reading each version straight from the catalog, so an override can't drift from what the catalog: pointers resolve to. That covers the singletons micro-frontends share at runtime, and it's also how a security fix reaches a dependency no repo declares directly: add it to the catalog at the patched version and list its name.

The overrides only guarantee a single copy inside each repo's own graph. Keeping a host shell and the remotes it loads at runtime on compatible majors is a federation and release-coordination problem. The catalog makes that much more likely, since every app on a cluster resolves the same versions, but it can't force separately built and separately deployed repos to agree.

The policy's version number tells you something, but it doesn't control anything. Every repo pins an exact version+sha512, so the policy's semver doesn't decide what a repo resolves. It tells a repo how much work the next version will be. Most releases are a patch: usually the security team bumping a governed dependency to its fixed version after a vulnerability turns up, with nothing breaking on repin. A minor adds or moves something the fleet can take without code changes. A major is kept for changes that break on repin, like a governed library moving to a new major. So a repo can tell from the version number alone whether the next step is a drop-in or a migration.

The Content-Aware Gate

The gate's job is to fail a build only when a dependency the repo actually uses has changed, never just because the repo is behind the latest policy.

The gate runs inside our shared CI pipeline library. Every web repo's CI configuration is a thin wrapper over that library, so the gate applies to the whole fleet from one place. Its logic is a short decision list:

pinned = the policy version this repo has pinned
ref    = dist-tags.latest if a stable policy exists, else the newest rc

if pinned == ref:
    PASS

# the repo's pin is behind the latest policy — but is that actually a problem?
moved = deps that (a) this repo references via catalog:
        AND (b) changed version between `pinned` and `ref`

if moved is empty:
    WARN + PASS      # "You're behind, but nothing you use moved. Repin at your convenience."
else:
    FAIL             # "A dependency you actually use changed. Repin to adopt it."

# plus: FAIL on a sha512 mismatch, or a pin that doesn't parse

(rc = a pre-release policy version; the gate prefers the stable latest and only falls back to the newest rc when no stable has been published.)

The content-aware gate decision: if the repo's pin equals the latest policy it passes; otherwise, if a dependency the repo uses changed it fails, and if nothing it uses changed it warns but passes.
The gate blocks only when a dependency the repo actually uses has moved. Otherwise, a stale pin passes with a warning. (A bad pin or a sha512 mismatch also fails.)

The gate doesn't compare version numbers. It looks at what changed that this repo is exposed to. If we move a dependency in your app's cluster and your app uses it, your next build fails until you repin. That's the right outcome, because a dependency you ship just changed. If we move something your app doesn't reference, or add a governed dependency it doesn't use, your build passes with a warning. "Uses" has a precise meaning here: the gate looks at the dependencies a repo declares as catalog: pointers, so a dependency pulled in only transitively won't trip it. Indirect dependencies go through the overrides instead. They take effect on a repo's next repin, but the gate doesn't force that repin. A repo also can't opt out by swapping a catalog: pointer back to a hard-coded version: the hook fails the install for any governed dependency declared with a literal version. The one way out today is removing the policy pin altogether, which the gate treats as a repo that isn't onboarded. That shows up plainly in the merge request, and we plan to close it with a CI check that requires the pin.

You don't have to push to find out what a bump will do: an audit you can run locally previews which of your dependencies a new policy moves, so the CI gate is a backstop rather than the first warning.

Adopting a New Policy

A policy change usually ships for one of three reasons: a security fix in a governed dependency, a new feature the fleet wants, or an Angular upgrade that moves a cluster forward. The flow is the same each time. Security fixes are the most common, so here's how one plays out. When the security team finds a vulnerability in a governed dependency, they bump its canonical version in the policy and publish it as a release candidate. Repo owners repin to it and test it on their own branches, and after a set period the security team promotes it to stable. The gate only warns about a release candidate and starts enforcing once it's stable. Upgrades follow the same path, driven by the team doing the upgrade. Each repin is a one-line change, the config dependency's version and hash in pnpm-workspace.yaml, and it goes through the repo's own merge request, so nothing changes in a repo without its team reviewing it. The gate backs this up. A repo that uses the bumped dependency can't keep shipping the old one, because its next build fails until it repins. A repo that doesn't use it stays green and repins whenever it's convenient. The fleet moves to the patched version one reviewed change at a time, instead of one CVE chased by hand at a time.

The gate only runs when a repo builds, though, so a repo nobody has pushed to in weeks won't hear about a security bump until its next build. Those repos aren't tracked automatically today. Our plan is to raise repin MRs automatically whenever a new stable policy is published.

One caveat: the policy centralizes the version decision, not the migration work. A patch or minor bump within a major really is edit once, repin everywhere. But when a governed dependency crosses a major, adopting it can mean real code changes in every consuming repo, and that work still happens repo by repo, by the team that owns it. The policy removes the hunting around: there's one target version, a gate that tells each affected repo exactly what moved, and one reviewed repin per repo instead of a dozen hand-made edits. Implementing the breaking changes is still each repo's job.

Most of that per-repo work is automated by an AI skill that handles onboarding and repins. It audits a repo against the newest published policy, flags any major bumps before touching anything, moves older repos onto pnpm 10, rewrites hard-coded versions into catalog: pointers, repins the config dependency, applies known breaking-change fixes, and checks the result against the gate. Anything it can't safely apply on its own, like a hard major upgrade, it hands to a human. We've open-sourced it: you'll find the full web-dep-policy skill in our Halodoc AI Skills Repository.

Results

Every web repository is now onboarded, so what started as a proof of concept is how the whole fleet manages dependency versions today. Here's what that gives us:

  • A dependency change now starts in one place. We edit one entry in policy.json and publish, instead of hand-editing N repositories and hoping we didn't miss one.
  • Publishing is safe by design. When we published the first stable policy against live pipelines, no repo's build broke, which is exactly what the design promised. Builds that were behind on dependencies they don't use passed with a warning, and the gate only ever blocks on a real mismatch in a dependency the repo uses.
  • The policy is reproducible and reversible. It ships as a package pinned by version and hash, so "which policy is this repo on?" has a one-line answer. Reverting a bad change is a roll-forward: we publish a new patch that restores the earlier version, and repos repin to it like any other update. The gate won't accept an older pin for a dependency a repo uses, so nobody slides backwards by accident.

What We Learned

Block on what changed, not on the version string. A gate that fails builds just for being behind gets disabled; one that fails only when something you ship has changed gets trusted.

The lockfile is the real contract. In our first prototype we compared the version numbers written in each package.json, and that wasn't enough: a version can look right on paper and still break the build once pnpm installs it alongside everything else. So the policy doesn't compare numbers at all. pnpm resolves each catalog: pointer into the lockfile, and before a version goes into the policy, we check that it installs cleanly with the packages around it.

Ship the policy as a versioned, hash-pinned package. A version number and an integrity hash turn "the shared config" into something you can pin, diff and verify byte for byte. A shared config is a convention people can drift from; a pinned package is a real dependency.

Running several framework majors at once is normal. Any real fleet is partway through some framework migration. A model that assumes one version per dependency will keep fighting that. Clustering the catalog by framework major lets the policy stay strict and honest about a fleet that's halfway through several upgrades.

Conclusion

Java gets a bill of materials almost for free with a parent pom.xml. Independently deployed JavaScript frontends have never had that, and the simple attempts to build one tend to break under their own rigidity. pnpm's catalogs and config dependencies finally give us the building blocks. Put a content-aware CI gate on top, and you get that bill of materials for a fleet of frontends.

Now that the fleet is onboarded, the next step is to grow the policy itself. We started with a core set of shared dependencies rather than every last one, and we're steadily bringing more libraries into the catalog until the whole shared surface is covered.

None of this is specific to Halodoc. If you maintain more than one frontend, a single versioned policy plus a gate that blocks on content drift rather than version lag is a pattern worth borrowing.

References

Join us

Scalability, reliability, and maintainability are the three pillars that govern what we build at Halodoc Tech. We are actively looking for engineers at all levels, and if solving hard problems with challenging requirements is your forte, please reach out to us with your resume at careers.india@halodoc.com.

About Halodoc

Halodoc is the number one all-around healthcare application in Indonesia. Our mission is to simplify and deliver quality healthcare across Indonesia, from Sabang to Merauke.
Since 2016, Halodoc has been improving health literacy in Indonesia by providing user-friendly healthcare communication, education, and information (KIE). In parallel, our ecosystem has expanded to offer a range of services that facilitate convenient access to healthcare, starting with Homecare by Halodoc as a preventive care feature that allows users to conduct health tests privately and securely from the comfort of their homes; My Insurance, which will enable users to access the benefits of cashless outpatient services more seamlessly; Chat with Doctor, which allows users to consult with over 20,000 licensed physicians via chat, video or voice call; and Health Store features that allow users to purchase medicines, supplements and various health products from our network of over 4,900 trusted partner pharmacies. To deliver holistic health solutions in a fully digital way, Halodoc offers Digital Clinic services, including Haloskin, a trusted dermatology care platform guided by experienced dermatologists.
We are proud to be trusted by global and regional investors, including the Bill & Melinda Gates Foundation, Singtel, UOB Ventures, Allianz, GoJek, Astra, Temasek, and many more. With over USD 100 million raised to date, including our recent Series D, our team is committed to building the best personalized healthcare solutions, and we remain steadfast in our journey to simplify healthcare for all Indonesians.

Tags

Pravesh S Shetty

SDE 2 at Halodoc