tbdex-js

This repo contains 3 npm packages:

@tbdex/protocol - create, parse, verify, and validate the tbdex messages and resources defined in the protocol draft specification
@tbdex/http-client - An HTTP client that can be used to send tbdex messages to PFIs
@tbdex/http-server - A configurable implementation of the tbdex http api draft specification

Development

This multi-package repository uses pnpm workspaces.

Prerequisites

Cloning

This repository uses git submodules. To clone this repo with submodules

git clone --recurse-submodules git@github.com:TBD54566975/tbdex-js.git

Or to add submodules after cloning

git submodule update --init

We recommend running the command below once which will configure your environment to only checkout the hosted directory under the tbdex git submodule directory, which contains files relevant to this repo, such as tbDEX spec test vectors and schemas.

git -C tbdex sparse-checkout set hosted

Hermit

This project uses hermit to manage tooling like node. See this page to set up Hermit on your machine - make sure to download the open source build and activate it for the project

Currently, we have these packages installed via Hermit (can also view by checking out hermit status):

node
pnpm

You can run hermit upgrade {package} to upgrade an existing package, or hermit install {package} to install a new package. Please see Hermit package management page for more details.

Running Tests

Note

Make sure you have all the prerequisites

clone the repo and cd into the project directory
Install all project dependencies by pnpm install
Build all workspace projects in this repo by running npm run build
run tests using pnpm test:node to run tests within a nodejs runtime
run tests using pnpm test:browser to run tests within a browser runtime. Before doing so, run npx playwright install --with-deps, only required once.

`pnpm` scripts

Script	Description
`pnpm clean`	deletes `dist` dir and compiled tests
`pnpm test:node`	runs tests in node runtime
`pnpm test:browser`	runs tests in headless browsers (chrome, safari, firefox)
`pnpm lint`	runs linter without auto-fixing
`pnpm lint:fix`	runs linter and applies automatic fixes wherever possible
`pnpm build`	builds all distributions and dumps them into `dist`

Publishing a new release

This project uses Changesets for semver management and releases. For motivations, see PR description here.

Release workflow:

Open a PR
changeset-bot will automatically comment on the PR with a reminder & recommendations for semver
Run pnpm changeset locally and push changes (.changet/*.md). The CLI tool will walk you through a set of steps for you to define the semantic changes and create a randomly-named markdown file within .changeset/.
Merge PR into main.
Profit from the automated release pipeline:
- Release Workflow will create a new Version Package PR, or update the existing one. For example, see this PR. This PR updates the version numbers in the relevant package.json files & also aggregates the Summary notes into the relevant CHANGELOG.md files.
- When maintainers are ready to publish the new changes, they will merge that PR and the very same Release Workflow will automatically publish a new version to NPM, and publish the docs to https://tbd54566975.github.io/tbdex-js/

Note

This is all achieved by the Changesets GitHub action being used in the Release Workflow.

Working with the `tbdex` submodule

Pulling

You may need to update the tbdex submodule after pulling.

git pull
git submodule update

Pushing

If you have made changes to the tbdex submodule, you should push your changes to the tbdex remote as well as pushing changes to tbdex-js.

cd tbdex
git push
cd ..
git push

sondreb/tbdex-js