Bit
What & Why
Bit is an open-source toolchain for component-driven development, it is a build time CLI tool that replaces package managers and takes full responsibility for managing all our dependencies.
Bit allows us to manage multiple apps within the same repository without duplicating all the configuration needed for the apps. Bit provides its own package repository which replaces npm.
To help gain a basic understanding of Bit please read the following
Managing Dependencies With Bit
Bit replaces npm, yarn or pnpm, we should never use these package managers for managing dependencies as they can cause problems when mixed with Bit.
Bit is configured to use pnpm as the package manager and there are a few places where we use pnpm to run scripts defined in package.json such as running data migrations and re-seeding the integration test database.
You should have Bit installed from the repository setup docs, assuming you do the following section outlines how we use Bit during day to day development.
The package.json in the root of the repo contains no dependecies as these are managed via the Bit workspace.jsonc file also in the root.
To install all dependencies for the repo use...
bit install
If you want to add an external dependency you do not need to specify whether its a dev or runtime dependency as Bit will determine this in a dynamic way when compiling and versioning our components.
To install an external dependency with or without a specific version use...
bit install typescript
bit install [email protected]
Bit Components
We organise our code into components, modules and services. A service is composed of multiple modules & components, a module is composed of multiple components. From Bits perspective all our components and modules are components.
If you want to add a new component or module, first create the directory on disk and add any source files, once you are ready to add the component to our workspace, use the following command, first one for componments, second for modules
bit add components/test --namespace components
bit add modules/geo/core --namespace modules/geo
The first argument to add command is the path to the component, the namespace should be componments for components and modules/[app_name] for modules.
When you are done building your componment and you area ready to version and export it to bit.cloud where we host our components follow these steps assuming your component is called "test"
bit build components/test // build the component and run any unit tests
bit tag components/test // tag the component with a new version (revision will be incremented) or for specific version use
bit tag components/test --build --ver 1.0.0 //tag the component with a specific version
bit export components/test // publish the component
The only time you should manually version components in this way is when they are first created, subsequent versioning is handled via the CI workflow.
Bit Compile & Watch
Our components or modules will depend on other internal components / modules and will reference those components via the node_modules folder in the @hectare folder.
When bit compiles our components it transpiles and copies the output to the dist folder in each component folder in the @hectare folder in node_modules.
When actively coding you do not want to have to keep manually compiling code to get the latest code in the build folders. Bit provides the watch command so you do not need to do this. Whenever you are coding you should have a separate terminal window open and run the following
bit watch
Bit will then monitor all our components and auto compile whenever they change.
When you pull or rebase main you may find bit watch starts erroring, sometimes it needs you to import the latest components for it to be able to continue compiling successfully, so after a pull or rebase from main its recommended that you stop bit watch, run bit import and start bit watch again.
Bit Environments
From the Bit docs...
Envs are reusable development environments for components. They are used to simplify and standardize component development workflows, like compilation. You may set different envs on different "types" of components. It means that a single command runs the same flow for all components in the workspace, regardless of specific tools or configs used.
We have build a custom environment for the repo which currently customises typescript compilation options.
The environment itself is a component: components/env
Look at env.extension.ts to see how we are customising the typescript compilation options for both build and production.
We should be able to customise the environment further to include specifications for things such as linting and prettier.
The key advantage is all our components can then share the same configuration which is only defined in one place.
Bit CLI
The following are some useful commands
bit build components/context // builds and runs tests for the specified component
bit show components/context // show the current configuration for a component including dependencies, files, extensions etc
bit test // run tests for all components
bit test components/context // run tests just for this components
bit link // recreates the symlinks between dist files in node_modules and source ts files
bit compile // recompile all source code
bit remove modules/customers/api --force
bit remove components/api --force
bit remove hectare.platform/components/elastic --force --remote
The full reference for the Bit CLI is here: https://bit.dev/docs/reference/cli-reference
Bit Cloud
Hectare has a space on bit's cloud where we publish all our components, you can acccess the Hectare cloud
https://bit.cloud/hectare/platform
credentials are in the Lastpass Dev Team Shared folder.
This is a great place to browse through our codebase, read documentation, review dependencies and available versions.
Troubleshooting
Hard Reset
Sometimes you may want to do a hard reset of your bit environment, we have a shortcut script to do this, this will tear down your bit environment locally and rebuild it, if you are having any weird problems that appear related to bit this will usually help.
bit capsule delete && rm -rf .git/bit && rm -rf node_modules && bit init && bit install