DEV Community: Shagun Sharma

Chapter 2: Architecting Cloak UI —Monorepos, Turborepo, and Frontend Patterns

Shagun Sharma — Tue, 09 Sep 2025 05:03:01 +0000

Welcome to the second chapter of my 10-Part Series — Building a Design System Agnostic UI Library 🚀.

In this chapter, we’ll dive into the architectural choices, tools, and challenges that shaped Cloak UI’s foundation.

Chapter 2 - Topics

Why Architecture Matters 🏗️
Different Frontend Architectures 🔎
Multi-Repo vs Monorepo ⚖️
Why Turborepo 🚀
The Challenges I Faced 🛠️
What’s Next 🔮

1. Why Architecture Matters 🏗️

When building Cloak UI, the challenge wasn’t just creating abstraction layers for buttons, inputs, or modals — it was designing a foundation that could actually support multiple design systems without turning into a tangled mess of code. 🧩

Architecture matters because it decides:

Flexibility 🔄 → can developers switch from one design system (like shad/cn) to another (like Radix or Hero UI) without rewriting everything?
Scalability 📈 → will adding new adapters or features break existing ones, or can the system grow naturally?
Collaboration 🤝 → can contributors easily understand the structure and extend it, or will they get lost in spaghetti code? 🍝

👉 For Cloak UI, the architecture isn’t just a behind-the-scenes decision — it’s the reason the project can actually deliver on its promise: helping teams escape UI vendor lock-in 🔓 while keeping their codebase clean ✨ and future-proof 🚀.

2. Different Frontend Architectures 🔎

Before settling on Cloak UI’s structure, I explored the common frontend architectures to see what really fits a design-system-agnostic UI library:

Monolithic Architecture 🏰 → Everything in one giant codebase. Great for quick MVPs, but scaling an open-source library this way is a maintenance nightmare.
Modular Architecture 🧩 → Breaks the project into smaller modules. Better than monoliths, but still doesn’t provide the separation needed when you’re supporting multiple adapters and utilities.
Component-Based Architecture ⚛️ → The DNA of modern frontend (React, Vue, etc.). Since Cloak UI’s entire premise is wrapping and adapting components, this naturally fits.
Microfrontends 🏗️ → Awesome for enterprise-scale apps with independent teams, but overkill for an open-source UI library.

👉 My takeaway: Cloak UI needed a component-first architecture ⚛️, but not in isolation — it had to be modular enough 🧩 so that tokens, utilities, adapters, and components could all evolve independently, without stepping on each other. This balance ⚖️ between component-driven design and modular organization became the foundation for Cloak UI. 🚀

3. Multi-Repo vs Monorepo ⚖️

One of the first architectural calls I had to make was where Cloak UI should live — should each package have its own repo, or should everything sit under a single roof? 🤔

Multi-Repo Approach 📦 → At first, it sounds clean: cloak-core, cloak-tokens, cloak-components, each in its own repo. But in practice, it’s chaos 😵. Shared configs have to be copy-pasted, tests don’t run across repos, and versioning becomes a constant headache. Maintaining five separate repos quickly feels like maintaining five separate projects. 🧨
Monorepo Approach 🏠 → Instead, everything lives in one repo. Tooling, configs, and types are shared. Contributors get the full picture in one place 👀, and CI/CD pipelines become simpler. ⚡

👉 For Cloak UI, the monorepo choice was obvious ✅. This isn’t just about convenience — it’s about creating a single source of truth 📖 where contributors, maintainers, and even future adapters can work together without friction. 🤝

4. Why Turborepo 🚀

After choosing a monorepo, the next step was figuring out how to manage it. There are a few popular options ⚙️:

npm/yarn workspaces 📦 → Great for small setups. But Cloak UI needed more than just package linking — features like build caching and pipelines were missing ❌.
Nx 🚀 → Extremely powerful, but also heavy 🏋️. For Cloak UI, which aims to stay lean and approachable for contributors, it felt like using a rocket to light a candle. 🕯️
Turborepo ⚡ → The sweet spot ✅. Lightweight, but packed with the features I actually needed — build caching, task pipelines, and smooth CI/CD integration.

👉 With Turborepo, builds became much faster ⏩, contributors could test just the component they were working 🔍 on instead of rebuilding everything, and the workflow stayed simple enough for anyone to jump in 🙌. For an open-source project like Cloak UI, that balance of simplicity + performance was exactly what I wanted. 🎯

5. The Challenges I Faced 🛠️

Of course, choosing a monorepo didn’t mean everything was smooth sailing ⛵. Setting it up for Cloak UI came with its own set of headaches 😅:

TSConfig Paths 🛣️ → TypeScript didn’t like resolving paths across multiple packages at first. After some trial and error 🧪, I fixed it with a base tsconfig and project references.
ESLint & Prettier 🎨 → Keeping consistent linting/formatting rules across all packages was messy 🌀. I ended up centralizing configs at the root 📂 and using overrides per package.
CI/CD Setup 🔄 → Getting linting, testing, building, and publishing all running cleanly in pipelines was tougher than expected. Turborepo’s caching made builds way faster ⚡, but it still took iteration 🔁.

👉 The biggest lesson? A monorepo isn’t “set it and forget it ❌.” It’s more like a living system 🌱 — you’ll constantly refine and optimize as the project grows.

6. What’s Next 🔮

Now that Cloak UI has a solid architecture in place 🏗️, the next step is setting up the developer experience 💻.

In Chapter 3, I’ll dive into the tools that make working on Cloak UI fun 🎉 and productive ⚡:

Storybook 📖 for visual previews,
ESLint & Prettier 🎨 for code quality,
Commit conventions 📝 for consistency,
And CI/CD 🔄 workflows for automation.

Stay tuned. Next chapter theme is going to be Mindcraft 🚀

Why I’m Building Cloak UI — The Pain of UI Vendor Lock-In 🚀

Shagun Sharma — Fri, 15 Aug 2025 03:53:32 +0000

Welcome to the first chapter of my 10-Part Series — Building a Design System Agnostic UI Library 🚀.

This series will document every step of the journey — from architecture decisions to real coding challenges (and yes, even the fails) 🌐🛠️.

📜 Chapter 1 - Topics

What is Cloak UI? 🐳
How Cloak UI is different from other libraries?
My Real World Struggles with UI Libraries 📦
The Real Problem: UI Vendor Lock-In 💻
How Cloak UI Solves This Problem 🖼️
Why This Matters for Frontend Developers & Teams 📦🚀
What’s Next?

1️⃣ What is Cloak UI! 🐳

Cloak UI is an open-source library that helps frontend developers build UI components without being locked into a specific design system or UI library.

Whether you're using Radix, shadcn/ui, Hero UI, or even custom components, Cloak UI provides a layer of abstraction that makes switching design systems as easy as changing a single config.

2️⃣ How Cloak UI is Different from Other Libraries

Most UI libraries are tied to their own component APIs, props, and theming systems. Once you pick a library, you are stuck with its way of doing things.

Cloak UI is different — it acts as a wrapper that sits on top of other libraries, giving you a single, consistent API to work with, no matter which design system you choose underneath.

3️⃣ My Real World Struggles with UI Libraries 📦

In one of my past projects, we started with Chakra UI. Midway through, the design team decided to switch to shadcn for better flexibility.

This switch turned into a nightmare — every button, modal, and form component had to be refactored because their props and structures were completely different. It wasted weeks of development time.

Another scenario — a new startup might want to quickly build and launch their website using prebuilt components to ship the product fast. But later, they might want to switch to their own design system for brand consistency and scalability.

In such cases, having a design-system-agnostic UI library would make the transition much smoother and far less time-consuming.

4️⃣ The Real Problem: UI Vendor Lock-In 💻

This is called UI Vendor Lock-In. Once you build your frontend using a specific UI library, switching later becomes painful.

Different libraries have different component APIs, prop types, and theme systems. This forces teams to stick with a vendor even when a better option comes along.

5️⃣ How Cloak UI Solves This Problem 🖼️

Cloak UI solves this by introducing an Adapter Layer that normalizes props and abstracts the differences.

You write your code once using Cloak's API, and under the hood, it connects to the actual UI library you've chosen.

Switching design systems becomes a matter of changing the adapter configuration, not rewriting components.

6️⃣ Why This Matters for Frontend Developers & Teams 📦🚀

For developers, Cloak UI removes the frustration of learning new prop structures when switching libraries.

For teams, it reduces the cost of vendor lock-in, speeds up design system migrations, and allows more flexibility in choosing the right tool for the job.

7️⃣ What’s Next?

In the next chapter, we'll dive into the frontend architecture principles that make Cloak UI design-system-agnostic.

We’ll explore concepts like Abstraction Layers, Prop Normalization, and Escape Hatches.

Stay tuned! 🚀