Observing useful tools and ideas for Monorepos in the wild… Lately, I’ve been hearing and talking a lot about ways to scale code-sharing. A popular topic is the “ ”, or a multi-package shared repository. monorepo Keeping separate packages inside a single repository is useful for code-sharing as it enables teams to share parts of their projects for other teams and projects to use, without the overhead of setting up and maintaining many repositories. For example, imagine an organization where different frontEnd teams wish to collaborate and work with shared React components. To support that, they built a shared React library (like or ). Pinterest’s Gestalt HP’s Grommet To make this possible they think about going “ ”; keeping all components in a single repository while each is its own package. This “useful evil” also makes it easier to contribute, run CI/CD and manage changes. monorepo In this post, I’ll review and share knowledge about the best and solution in the ecosystem for making this possible. Feel free to comment and suggest your own insights and tools from your experience! tools 1. Bit component monorepo The thing about is that every repository is already a monorepo. Bit You don’t need to refactor anything. You don’t need to restructure the project, set up different packages, define files or anything else. package.json Instead, you just need to add Bit to the repository and share the components. This becomes possible thanks to Bit’s ability to automatically isolate components from the project, including all their dependencies and more. Dozens of components can be shared within minutes from adding Bit to the repository, to become available in , where they can be organized, shared and played-with online, then installed with NPM and Yarn. Bit’s hub When you make changes to one component in the repository, Bit will automatically track the changes and identify other components which use it as a dependency. Then if you run you can see all the components which were automatically modified as their dependency was modified. bit status Made changes to 1 component in the repo; Dependents were automatically updated Meaning, no manually going through files to manage changes to dependencies, as Bit does this work for you to make your monorepo maintenance much simpler. package.json You can also add Bit to your library’s release management (CI/CD) to update the components on every release with all the changes. Since Bit runs, build and test your components, you can quickly learn the new status of everything. PRs can be made directly to the monorepo, or via which lets others import and develop components right from their end project. bit import To sum up, if you have a component library you want to make a multi-package monorepo, Bit is probably the fastest and lowest-effort way to go about it. It also provides added values as discoverability, an online community and more. . Give it a try Example Semantic-UI component library before Bit. _The official Semantic-UI-React integration. Contribute to Semantic-Org/Semantic-UI-React development by creating an…_github.com Semantic-Org/Semantic-UI-React Semantic-UI component library with Bit (0 refactoring). _The official Semantic-UI-React integration. Contribute to teambit/Semantic-UI-React development by creating an account…_github.com teambit/Semantic-UI-React . Components shared with Bit Pros 0 refactoring to the repository. It takes minutes from 0 to publishing 100 packages from your existing library. Try it. Scalable code-sharing without the overhead. Great visual for components. discoverability Bit automatically manages all dependencies in the repo, including changes to component dependencies, and updates all components as required. No different files to maintain or update. package.json Change management can be done via PRs to the repo, or via issuing component updates from any other repository by importing a component, making changes and issuing an update to the original repository. Automated updates on releases (Bit in CI/CD). Cons Extension system is coming up. Until then, you might have to modify build/test environments a bit for different tools you work with. Install as packages via Bit’s registry with the NPN/Yarn clients (your choice). Not supporting NPM’s registry. All the hub’s features (search, playground, npm install) require that you host code in the hub (like GitHub and NPM). There’s no vendor locking (Bit is distributed like Git and can be set up on any server). 2. Lerna Monorepo Lerna is a tool for managing multiple packages within a single repository. With Lerna you can refactor your repository to keep multiple packages within it, while Lerna allows you to link dependencies ( and version them all separately or together as you choose (Independent mode would mean that every sub-package would have its own semver and get updated accordingly when its dependencies got updated). lerna bootstrap) my-lerna-repo/ package.json packages/ package-1/ package.json package-2/ package.json Lerna automates tasks for packages in the monorepo. The will run inside each sub-package and will publish all packages to npm and will update git tags, etc. Then, packages can be installed from NPM’s registry. lerna run build npm run build lerna publish Lerna requires some work at the get-go and more along the way, but is a solid way to keep a small number of core packages in a single repository and publish each independently to NPM. Some open-source projects use Lerna to handle core packages, including Babel, Jest and Gatsby. It has many tutorials and posts around the web. It’s particularly useful for managing several parts of a single project in one repository, while each is a stand-slone “mini-project” on its own. Example . Babel packages with Lerna _🐠 Babel is a compiler for writing next generation JavaScript. — babel/babel_github.com babel/babel Pros Mature and plenty of tutorials around the web. Version all packages separately or in a single line. Link dependencies in the project with . lerna bootstrap Automation for task execution for all packages in the repo. publishes all updates to NPM. Lerna publish Cons Heavy refactoring for the repository. A lot of initial overhead. Maintenance overhead grows with different and environments for every package. package.json Discoverability for packages relies on NPM/library's docs. PRs can only be made in the repo, and it can be hard to onboard new developers into the repo, which in turn impairs adoption of packages. 3. Bit + Lerna + Yarn workspaces combo Lerna and Bit can play together in a single repository. For example, Lerna can be used to manage the core packages while Bit can be used to share all smaller components. Bit also provides discoverability for components, and reduce the amount of refactoring and maintenance needed. The two can also play with Yarn workspaces. While Bit will automatically manage dependencies between the components in the repository and Lerna will help you handle larger core packages, Workspaces will help consolidate and optimize the installation of external packages in the repository. Pros Use Lerna to handle 3–4 larger packages in the library while Bit will handle the dozens of components. No overhead for sharing any number of components from the repo. Discoverability for components and simpler collaboration. Combine with Yarn workspaces to optimize workflow and performance. Cons Use 2 tools instead of 1. You’ll have to manually maintain the larger packages. Use 2 package registries (both work with the NPM client so after running 1 command it shouldn’t affect internal consumption). 4. Git submodules Git is the SCM of choice for most dev-teams. It allows you to put one repository of another repository, creating a for the entire project, and one project can use code from another project. as a subdirectory single working-tree But… Git submodules is, for most developers, a painful topic. First, they only work on branch. Second, submodules create highly coupled code between projects and make it hard to merge and collaborate on cross-repo tasks. A submodule repo also has no idea that it is nested, and might have a dependent repo. master There are various tools that provide additional automation around the Submodule feature, such as , , and . These tools try to improve some of the usability issues of Submodules, but are not supported by a specific vendor and have different drawbacks. git-subtree gitslave braid giternal Conclusion The discussion around Monorepos is thriving in the community. While most agree on the virtues of a multi-repo architecture, some use-cases make it just too hard to maintain and publish multiple packages from multiple repositories. Particularly, when working on a shared library. To make this easier, new tools emerged in the ecosystem. From Lerna which automates the setup around keeping and publishing larger packages in a single repository, to Bit which takes the experience around component libraries to the next level, at 0 effort and with all the benefits. Down the line don’t forget, that sharing code is about technology but also about people. You and your team have to be oriented to writing reusable code, thinking in modularity and encourage communication and efficiency. Thanks for reading, and please don’t hesitate to comment below and ask anything. Cheers
