Skip to main content

Understanding the Bitbybit GitHub Monorepo

Welcome to this overview of the main Bitbybit GitHub monorepo. This page serves as a guide to understanding its structure, its contents, and how it all fits together to power the Bitbybit platform.

➡️ Main Repository URL: https://github.com/bitbybit-dev/bitbybit

This monorepo is the central hub for the core 3D development of Bitbybit

What is a Monorepo? And Why Do We Use One?​

A "monorepo" (monolithic repository) is a software development strategy where code for many different projects or packages is stored in the same version control repository.

For Bitbybit, this approach helps us:

  • Manage interconnected packages: Our core algorithms are often used together and can have dependencies on each other.
  • Ensure consistency: Shared tooling, linting, and build processes can be applied across all packages.
  • Streamline development: Changes that affect multiple parts of the platform can be made and tested in a single place.

Primary Language: TypeScript​

The dominant programming language you'll find throughout the bitbybit monorepo is TypeScript. We chose TypeScript for its:

  • Strong Typing: Helps catch errors early, improves code maintainability, and makes refactoring safer.
  • Enhanced Developer Experience: Features like autocompletion and better tooling are invaluable.
  • Suitability for Complex Systems: Essential for building a robust platform like Bitbybit, especially one that supports visual programming.

What's Inside the Monorepo? Key Components:​

The bitbybit-dev/bitbybit monorepo houses several critical parts of the platform:

1. Core Algorithmic Packages (NPM)​

A significant portion of the monorepo is dedicated to individual NPM packages. Each package typically encapsulates a specific set of functionalities or algorithms related to 3D geometry, CAD operations, or utility functions. Examples include:

  • Packages for creating points, lines, curves, surfaces, and solids.
  • Packages for performing geometric transformations, intersections, and analysis.
  • Wrappers and integrations for CAD kernels like OpenCascade Technology (OCCT), Manifold or JSCAD.
  • Utility packages for common tasks.

These packages are designed to be:

  • Modular: Usable independently or in combination.
  • Published to NPM: Allowing developers to use Bitbybit's capabilities in their own TypeScript/JavaScript projects.
  • The backbone of Bitbybit: They power the higher level proprietary Bitbybit platform and visual programming editors.

You'll typically find these packages within a packages/dev directory in the monorepo.

2. The Documentation Site (Docusaurus)​

This very documentation site is built using Docusaurus and its source files (Markdown, React components, configuration) reside directly within the bitbybit monorepo, in a docs/ directory. This colocation makes it easier to keep documentation in sync with code changes.

3. Example Applications​

We’ve built a variety of example apps that integrate our NPM packages under examples/ folder. These apps are set up using popular frameworks such as React, Angular, Nuxt, Next.js, and others. We even include a few examples that run Bitbybit within a Node.js backend environment.

It’s important to note that the latest and most up-to-date apps are located in the examples/vite folder. This folder contains projects used as live demos on StackBlitz and integrated directly into this documentation site.

4. Architectural Philosophy​

As you explore the codebase, particularly the algorithmic packages, you'll notice a consistent and somewhat strict architectural style. This is intentional and crucial for a key goal of Bitbybit: to seamlessly support higher-level visual programming editors (like those based on Rete.js or Blockly).

These architectural rules ensure:

  • Clear API Definitions: Functions have well-defined inputs, outputs, and types, making them easily translatable into visual blocks.
  • Predictable Behavior: Consistent patterns make it easier to integrate algorithms into visual workflows.
  • Type Safety for Visual Editors: TypeScript's type information is leveraged to provide rich feedback within the visual editors.

Understanding this underlying principle is key to understanding the "why" behind some of the code structure.

What's NOT Inside the Monorepo?​

While this monorepo hosts all of the open-source components of Bitbybit, it does not include any proprietary source code. We do not open-source the source code for our higher-level visual programming editors, advanced algorithms, or the main website.

The Bitbybit platform also includes proprietary 3D configurators and closed-source applications. Additionally, the 3D Bits application for Shopify is not open-sourced.

How to Engage with the Monorepo​

There are several ways to interact with and benefit from the monorepo:

  • Browse and Learn: Explore the code to understand how specific algorithms are implemented or how the platform is structured.
  • Use the NPM Packages: If you're a developer, you can install and use the published NPM packages in your own projects.
  • Contribute:
    • Code Contributions: If you're interested in contributing to the algorithms or core platform features, please check out our Contribution Guidelines.
    • Documentation Improvements: The documentation is always a great place to contribute. Enhancing clarity, adding examples, or fixing typos directly helps the community. PRs to the docs folder are welcome!
    • Blog Posts: If you’ve built interesting projects using Bitbybit and want to share your story, you're welcome to submit a pull request with a Docusaurus blog entry. We advise to discuss your idea first with us via info@bitbybit.dev. Blog posts should be placed in the docs/blog folder. Don’t forget to add your information to docs/blog/authors, including your name. If your blog post is accepted, we reserve the right to share it on our social media channels—though we are under no obligation to do so. Please note that we also reserve the right not to merge your pull request, which means your blog post may not be published.

The examples folder​

It's important to note that while the core libraries live in the main bitbybit/packages/dev folder, we also ported our application examples to this same monorepo:

➡️ https://github.com/bitbybit-dev/bitbybit/examples

App examples host various standalone applications and demos that showcase how the released Bitbybit NPM packages can be used in different contexts. It serves as a practical demonstration ground for the open-source libraries developed for Bitbybit.

Summary​

The bitbybit-dev/bitbybit monorepo is the engine of Bitbybit. It's where our core TypeScript algorithms are developed, packaged for NPM, and where our example apps with documentation lives. Its structure is carefully designed to support both direct library usage and integration into powerful visual programming environments.

We encourage you to explore it, learn from it, and consider contributing to its growth!