<p align="center"> <img src="./assets/images/caravan-logo-transparent.png" /> </p>

Caravan Monorepo

Introduction

This is a monorepo project for the Caravan FOSS ecosystem, built with Turborepo.

There are two primary directories for managing projects:

• apps
• packages

The main app is a webapp forked from the original Caravan project which is being re-branded as the "Caravan Coordinator". The goal is to have many more applications built within this ecosystem that can live under the caravan/apps directory.

caravan/packages is where the utility libraries live. Their foundation are forked versions of the unchained-bitcoin and unchained-wallets projects. These are being re-branded for legacy support as @caravan/bitcoin and @caravan/wallets but moving forward the expectation is that they will be split up as well. For example the psbt module in @caravan/bitcoin will become @caravan/psbt.

Try Caravan now!

Goals

There are a few goals for this new conception of the "Caravan" project.

• Caravan is a familiar and trusted name in the javascript FOSS bitcoin ecosystem. Having the utility libraries that the coordinator relies on be under the same umbrella makes that relationship clearer
• Scoping libraries will help protect from supply chain attacks
• Moving the project into a monorepo will help improve and streamline the developer and deployment experience. Being able to test changes to the libraries in the coordinator immediately will create a faster feedback loop for development.
• Having tightly scoped libraries will make code easier and safer to audit and build out.
• Having a unified set of developer tooling (linting rules, deployment automation, etc.) also improves developer QoL and code reliability.

Developers

The monorepo setup should make it easier for developers to test their changes in a more realistic environment, especially when making changes to libraries that are dependencies of the coordinator.

In the caravan monorepo we use changesets to manage versioning and releases. A changeset will be required for PRs to be merged. Read below to learn more.

Changesets

Quickstart

Any PR to caravan that introduces a functional change requires a changeset be submitted with it.

Simply run the following command and follow the cli instructions:

$ npm run changeset

Learn about semantic versioning if you are unsure whether your changes qualify as a patch, minor, or major change.

Pull Requests are checked for changesets by the changeset-bot.

Changesets GitHub Actions are run to create a version PR and publish on merge.

About Changesets

This is the recommended way by Turborepo to handle changelogs, versioning, and releases. It's designed first as a manual process, so by default it won't "yell" at you to do things correctly. This adds more flexibility over something like commitlint which can have a steep learning curve and frustrating for new contributors.

Read the documentation for adding a changeset here

And another good resource for what the workflow should look like here

What is a changeset?

A changeset is a Markdown file with YAML front matter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML front matter describes what packages have changed and what semver bump types they should be

(source)[https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md#the-solution-changesets]

Relevant tooling

• CLI generation of new changesets
• Automated consumption of changesets to do versioning
• Detection + surfacing of changesets in PRs

Automating Changesets

Node.js Version Management

Required Versions

This project enforces specific Node.js and npm versions to ensure consistent lockfiles across all contributors:

{
  "engines": {
    "node": ">=20.18.0 <21.0.0",
    "npm": ">=10.5.0 <11.0.0"
  }
}

Setup

Use the correct Node.js version before working on the project:

$ nvm use                    # Uses .nvmrc file
$ npm install               # Automatically checks versions

Pre-commit Hooks

Husky automatically runs pre-commit checks that:

• ✅ Verify your Node.js version matches requirements
• ✅ Validate package-lock.json changes are consistent
• ✅ Run linting (if available)

Common Issues

Version mismatch during install:

$ nvm use 20.18.0
$ npm install

Pre-commit version error:

$ nvm use
$ git commit    # Try again

Large lockfile changes warning:

• Usually means wrong Node.js version was used
• Check node --version and ensure it matches requirements
• Re-run npm install with correct version if needed

The system prevents lockfile conflicts by ensuring everyone uses compatible Node.js/npm versions.

Getting started

Quickstart

Clone the repo, install all dependencies, and run dev instances of everything.

(Checkout the README for caravan/descriptors to make sure you can build the wasm dependencies.)

Install nvm and run below commands in your terminal.

$ nvm use
$ npm install turbo --global
$ git clone https://github.com/caravan-bitcoin/caravan.git
$ cd caravan
$ npm install
$ turbo run dev --concurrency 11 # or `npm run dev`

What's happening?

The turbo.json file is the main config for the monorepo. You can read about running tasks in Turborepo here.

Note:

After you've declared a task in turbo.json, it's up to you to implement it in your package.json manifests. You can add scripts all at once, or one workspace at a time. Turborepo will gracefully skip workspaces that don't include the task in their respective package.json manifest.

The main scripts to be run are defined in this config file: build, lint, test, and dev.

Development

One of the main benefits of a monorepo for this type of project is being able to easily work with multiple dependencies you're developing at the same time. Note for example that in the caravan/coordinator's package.json, the dependencies from the monorepo are referenced with a simple * rather than a version or repository location.

Running commands

$ turbo run test:debug --scope=@caravan/bitcoin --no-deps --no-cache

• scope says you want to just run the command for that package (@caravan/bitcoin)
• --no-deps is optional and says to skip any related packages. Without this, everything else that depends on @caravan/bitcoin will also be run
• --no-cache also optional and self-explanatory. Usually not necessary but turborepo does a lot of cacheing so good to be aware of.

Dependencies

The --no-deps option highlights a lot of the benefits of the monorepo. If you make a change in one library, anything else that relies on it should be tested to make sure they're not broken too. If you want to break this coupling, a published package version can be referenced instead of using * (this is not recommended however).

Note about internal packages

Sometimes it makes sense to move code you want to share between packages into an internal package. In fact this is recommended by Turborepo.

When you're creating Internal Packages, it's recommended to create packages that have a single "purpose".

Internal packages should be added to the devDependencies list of the packages/apps that depend on them. This is because the bundlers (tsup by default in caravan) won't include dependencies into the bundle and then when the package is attempted to be installed by external downstream projects it will try and find the internal dependency in a remote registry (which will fail). By including it in the devDependency:

• the dependency graph will be correct
• the bundler will build it in with the final package
• other projects won't try and install the internal dependency

@caravan/multisig is an example of such a package that is depended on by other packages like @caravan/psbt and @caravan/wallets.

Adding a new package

NOTE: Turborepo provides code generator capability for bootstrapping a new project. You can run turbo gen or npm run gen from the root of the project and you will be pr