RFC: Monorepo management

[matheusps]

Monorepo Management

This is a proposal on how the shoreline repository package management will work. It includes a brief context of Monorepos, the set of tooling that we use, and the CI/CD.

Context

To be more accessible to readers of different contexts, this is a short context of Monorepos.

What is a Monorepo?

A Monorepo, short for "monolithic repository," is a software development approach where multiple projects or components are stored within a single, unified repository. In other words, instead of having separate repositories for each project or component, all the code and related assets are housed in a single version control system.

Why do we use a Monorepo?

It has numerous advantages including, but not restricted to:

1. Code sharing and reusability: Having all projects in a single repository encourages code sharing and reuse across different components, leading to increased efficiency and consistency.
2. Simplified dependency management: Dependencies between projects can be managed easily, reducing conflicts and ensuring consistent versions across the codebase.
3. Easier collaboration: With all code in one place, teams can collaborate more effectively, sharing knowledge, and best practices, and making cross-component changes more seamlessly.
4. Streamlined testing and deployment: Testing and deploying changes across multiple projects becomes easier as they are all housed in a single repository, allowing for coordinated and consistent release processes.
5. Enhanced code visibility and discoverability: Developers can easily explore and understand the entire codebase, making it simpler to identify shared components, understand dependencies, and locate relevant code.

Tooling

• Pnpm: Package manager
• Turborepo: Build system.
• Lerna: Packages publishing.
• Commitizen: Commit tool for semantic release.

Why pnpm over yarn?

One compelling reason to choose pnpm over yarn is its unique approach to dependency management. Unlike yarn, pnpm uses a single shared store for all packages within the repository. This means that common dependencies are not duplicated across different projects, resulting in significant disk space savings and faster installation times. This efficiency is particularly beneficial in Monorepo setups where multiple projects share dependencies. Additionally, pnpm supports a flat dependency structure by default, which avoids nested folders and reduces the potential for conflicts or version mismatch issues. It is also compatible with the npm registry, allowing for seamless integration with the existing JavaScript ecosystem.

Consider looking into the references:

• Pnpm motivation.
• Benchmarks of pnpm against other package managers.
• Yarn benchmarks data.
• Rush's documentation on Phantom Deps.
• Rush's documentation on npm doppelgangers

Bundle

A JavaScript bundler is a tool that combines multiple JavaScript files and their dependencies into a single file, known as a bundle. It analyzes the code and its dependencies, resolves any import statements or module dependencies, and merges them into a single file. This process enhances performance by minimizing network overhead and reducing the file size, resulting in faster loading times for users. Additionally, JavaScript bundlers often include optimizations such as minification and tree shaking to further optimize the bundle's size and remove unused code.

We have two bundle setups:

• Rollup: Custom Rollup builds.
• tsup: Simple typescript builds that don't bundle CSS.

CI/CD

• Github Actions: Self-serviced automations.

Next Steps

In the future, we intend to extend our Monorepo architecture to be used throughout VTEX frontend teams. This should be achieved by creating a new pipeline for the DK CI/CD.

[lucasaarcoverde]

I'm convinced with the change to pnpm. LGTM ✨

[marcelovicentegc]

pnpm for the win!

[matheusps]

Implemented