Thoughts on Development and Repository Strategies: Monorepo vs. Multi-repo
While managing this blog and building multiple products (like KuroCMS, KuroEditor, and KuroNote), file management became overwhelming. Here is a reflection on multi-repo vs. monorepo strategies.
Troubles Experienced with the Multi-repo Approach#
- Inconsistent Release Workflows: The process from code update to product release differed across each product and shared library, creating unnecessary confusion and complexity.
- Duplicate Code and Drift: Products like KuroCMS and KuroNote utilize KuroEditor. Because they lived in separate repositories, copies of KuroEditor were duplicated into each project. Inevitably, the latest updates drifted out of sync. When using AI coding assistants, the AI would frequently edit the duplicate copies instead of the source library, resulting in conflicting codebases.
- Scattered Secret Management: Configuration secrets like
.envfiles (Worker secrets, deployment passwords, etc.) existed in every individual product folder. Managing them across projects became messy, and having identically named variables across environments caused prolonged, hard-to-debug errors.
As development scaled, the downsides of multi-repo setups became glaringly obvious. However, it is also worth discussing the advantages that multi-repo architectures offer.
Advantages of Multi-repo#
- High Independence: Each project can independently manage permissions, CI/CD pipelines, and tooling. In web apps, pairing GitHub Actions with git pushes enables automatic production deployments. However, GitHub Actions free tiers have limited build minutes, which run out quickly with frequent deployments. While fine for enterprises with large budgets, solo developers often find simpler management by deploying directly to Cloudflare using CLI tools like Wrangler.
- Lightweight and Fast: Because each repository only contains a single product, repository sizes remain small, making cloning, branching, and checking out code extremely fast.
- Contained Blast Radius: Bugs or breaking changes within one repository rarely impact unrelated systems directly.
However, Deploying to Cloudflare via Wrangler Has Its Own Challenges
The biggest friction is switching between logged-in user accounts in Wrangler. Juggling personal and organization accounts often forces repeated OAuth re-authentication. For developers who must switch environments, it is highly recommended to leverage Wrangler's environment switching and environment variable capabilities. This lets you switch between pre-authenticated profiles seamlessly during command execution. Highly recommended.
What is the Contender: The Monorepo?#
As the name implies, a monorepo consolidates all products, libraries, and tools into a single repository. While it may sound blunt, it elegantly resolves many of the pain points found in multi-repo workflows.
<Advantages>
- Effortless Code Sharing: No need for duplicate code copies. Because all projects reside in the same repository, shared modules can be imported directly via relative paths. Code is structurally guaranteed to stay up to date. This also prevents AI assistants from mistakenly modifying disconnected copies.
- Seamless Cross-Cutting Changes: When updating shared API schemas or client libraries, breaking changes can be refactored and committed in a single atomic commit. This is an enormous advantage when pairing with AI. AI agents can easily lose context when switching between fragmented sessions. Splitting libraries into separate repositories forces AI into disjointed contexts, leading to hallucinations and unexpected behaviors—even when guidelines are documented in AGENTS.md.
- Clear Holistic Visibility: Having the entire codebase in one location makes it easy to reference other modules, fostering better architectural consistency.
<Disadvantages>
- Repository Growth: As code accumulates, cloning, building, and testing can take longer. However, modern Git features like sparse checkouts, partial clones, and path-filtered commits make monorepos just as fast and nimble as multi-repos in practice.
- Complex Permissions and CI Configuration: Granular access control and CI pipelines require careful orchestration when running against a single repo. For Kurousagi's projects, however, mobile applications are the main frontier, and heavy browser-based CI/CD pipelines add little value over direct CLI deployments via Wrangler. Since the team consists of a solo developer, enterprise-style access control is not an issue.
What Exactly is CI/CD?
CI/CD stands for Continuous Integration and Continuous Delivery / Continuous Deployment. In short, it refers to the development methodology of frequently releasing code to staging or production environments to gain immediate feedback and accelerate development speed. Common implementations combine GitHub Actions with deployment scripts so that pushing code automatically triggers builds and deploys.
In that sense, it shares the same spirit as past methodologies like Agile Development and Extreme Programming (XP), with CI/CD placing particular emphasis on automated deployment.
Monorepos: A Battle-Tested Standard at Tech Giants#
In reality, many of the world's largest tech companies have relied on monorepos for years. Tech giants like Google, Meta, and Microsoft are well known for managing billions of lines of code across tens of thousands of engineers inside massive monorepos. High-growth innovators like Uber, Stripe, Airbnb, and Spotify have also adopted monorepos to eliminate redundant code reproduction.
While enterprise giants build custom internal tooling and invest heavily into bespoke infrastructure to manage monorepos, generous modern GitHub free tiers and lightweight tooling now allow solo developers and small teams to reap the full benefits of a monorepo with smart workflows.
Structuring code into a clean, unified architecture maximizes reuse for future products. Especially in the AI era, a streamlined monorepo structure empowers AI assistants and drastically accelerates development velocity.