So, you're building an internal platform that covers lots of different groups, teams, and places to deploy. The way you set up your code isn't just a minor detail — it's a big decision that gets even bigger over time. Here's how we moved QuokkaQ, a system for managing queues across 14 offices and 36 different queues, from a messy codebase into a neat Nx monorepo, and the cool stuff we learned while doing it.
The Problem: One Codebase, Too Many Directions
QuokkaQ started as a focused product: a single queue management interface backed by a Go service. But internal platforms have a way of growing sideways. Over time, the system expanded to include:
- A customer-facing kiosk UI (tablet, touch-first)
- An operator dashboard (desktop, data-dense)
- A shared component library used by both
- A Go backend with PostgreSQL, Redis, and WebSocket support
- CI/CD pipelines with semantic versioning and Yandex Cloud deployments
What had started as two repositories became five, with shared code copy-pasted between them. Changes to a shared component meant updating it in multiple places. CI pipelines had drifted out of sync. Releases required coordinating across repos manually. Every deployment felt riskier than it should have.
We needed a structural reset.
Why Monorepo, and Why Now
The decision to consolidate into a monorepo wasn't about following a trend — it was about eliminating a specific class of problems:
Shared code without shared ownership. When the same Button component lives in two repos, it will eventually diverge. Not from malice, but from the natural pressure of deadlines. A monorepo makes sharing the default, not the exception.
Fragmented CI. Five repos meant five pipeline configurations, each slightly different, each requiring separate maintenance. Bugs in CI setup propagated slowly and silently.
Difficult cross-cutting changes. Renaming an API response field meant touching the backend, the kiosk UI, and the dashboard in three separate PRs, coordinated manually. In a monorepo, that's one PR with one review.
The question wasn't whether to use a monorepo. It was which tool to use — and how to migrate without stopping feature development.
Evaluating the Landscape
We looked at the major options: Turborepo, pnpm workspaces with manual scripts, and Nx.
Turborepo was appealing for its simplicity — great for pure JS/TS projects. But QuokkaQ isn't purely JS. We had a Go backend, a React frontend, and aspirations to add a mobile app. We needed something that could model tasks and dependencies across different tech stacks, not just run npm scripts faster.
Plain pnpm workspaces gave us package sharing but nothing more. We'd have to build our own task graph, caching, and affected-detection logic. That's essentially reinventing what Nx already does.
Nx won because it matched how we actually think about the project. It models the repository as a graph of projects with explicit dependencies, and it uses that graph to answer the question we kept asking: given this change, what do I actually need to rebuild and retest?
The Migration: What We Did
We didn't do a big-bang migration. We couldn't afford the downtime in a system with real operational queues running 8+ hours a day.
Instead, we ran a strangler fig migration: create the Nx workspace, move one project at a time, and keep everything deployable throughout.
Step 1: Create the Nx workspace alongside existing repos
We initialized a new Nx workspace and started by moving the shared component library first — it had the fewest external dependencies and the most to gain from centralization.
npx create-nx-workspace@latest quokkaq --preset=ts
We chose the ts preset rather than a framework-specific one, because we needed to support React apps, a Node backend, and eventually Go tooling — and we didn't want Nx's generators to assume a single framework.
Step 2: Define the project graph explicitly
Nx infers dependencies from imports, but for a migration, we wanted to be explicit. We defined project.json for each package and declared dependencies manually first, then let inference take over once the structure stabilized.
// apps/kiosk/project.json
{
"name": "kiosk",
"targets": {
"build": {
"executor": "@nx/vite:build",
"dependsOn": ["^build"]
},
"test": {
"executor": "@nx/vite:test"
}
}
}
The "dependsOn": ["^build"] was key — it told Nx that before building the kiosk, it must build all upstream libraries. No more "it worked locally but CI failed because the lib wasn't built" incidents.
Step 3: Enforce boundaries with module boundary rules
With shared code accessible to everyone, the temptation to take shortcuts is real. We used Nx's @nx/enforce-module-boundaries ESLint rule to declare which projects could import from which others:
// .eslintrc.json
{
"rules": {
"@nx/enforce-module-boundaries": [
"error",
{
"depConstraints": [
{
"sourceTag": "scope:kiosk",
"onlyDependOnLibsWithTags": ["scope:shared", "scope:kiosk"]
},
{
"sourceTag": "scope:dashboard",
"onlyDependOnLibsWithTags": ["scope:shared", "scope:dashboard"]
}
]
}
]
}
}
This meant a developer working on the kiosk couldn't accidentally import dashboard-specific logic, even if it was technically accessible in the monorepo. Violations surfaced immediately in the editor, not in code review.
Step 4: Nx Affected in CI
This was the change that made the biggest difference to our day-to-day workflow. Before, every CI run built and tested everything. After:
# GitHub Actions
- name: Run affected tests
run: npx nx affected --target=test --base=origin/main
- name: Build affected apps
run: npx nx affected --target=build --base=origin/main
On a typical feature branch touching only the operator dashboard, CI went from ~18 minutes to ~4 minutes. The affected graph knew that changes to libs/ui needed to retest both apps, but a change isolated to apps/dashboard only needed to retest that app.
What We Got
After the migration was complete, the difference was measurable:
CI time dropped significantly for most PRs — changes to isolated apps no longer triggered full rebuilds.
Shared component drift effectively stopped. There's one Button, one Queue type definition, one set of API response interfaces. When we update them, every consumer gets the update immediately and TypeScript tells us if something breaks.
Onboarding became easier. New team members had one place to clone, one set of commands to learn, and Nx's project graph visualization (nx graph) gave them a map of the whole system on day one.
Release coordination went from a manual checklist to a structured process. Semantic versioning and changelogs are generated per-project, but triggered from a single pipeline.
The Trade-offs We Accepted
Nx is not free. Here's what we paid:
Build configuration complexity. Nx adds a layer of configuration on top of whatever tools you're already using. Getting Vite, Jest, and Playwright to play nicely within Nx executors required some upfront investment. The docs help, but expect friction for non-standard setups.
The dependency graph can lie. Nx's affected detection is only as good as the dependency declarations. If you forget to declare a dependency — or if you have runtime dependencies that aren't reflected in imports — you'll get false negatives where Nx thinks something isn't affected when it is. We caught a few of these early; now we have a checklist for adding new projects.
Nx Cloud is tempting but not free. Local Nx caching is genuinely useful and free. Remote caching via Nx Cloud is significantly better for teams, but it's a paid product. We evaluated it and decided to hold off for now, running local caching only.
Would We Do It Again?
Yes — and we already have. The patterns we developed for QuokkaQ became the template for how we structure new internal platform work.
The key insight is that a monorepo isn't a solution to bad architecture. If your code is tangled, moving it into a monorepo makes it more-conveniently tangled. Nx gave us the tools to define and enforce structure, but we still had to do the design work to figure out what the right structure was.
If you're building a multi-tenant internal platform with shared UI, a Go or Node backend, and plans to expand — the cost of Nx setup is paid back quickly. The affected build detection alone is worth it at scale.
Resources
Building internal platforms at scale? I write about queue systems, developer tooling, and real-time architecture. Follow me on Dev.to or connect on LinkedIn.
