Skip to content
This repository has been archived by the owner on Dec 12, 2024. It is now read-only.

TBD54566975/tbdex-js

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Diane Huxley
Feb 16, 2024
79f1958 · Feb 16, 2024
Feb 13, 2024
Jan 25, 2024
Jan 23, 2024
Feb 16, 2024
Feb 6, 2024
Sep 12, 2023
Jan 11, 2024
Jan 11, 2024
Sep 12, 2023
Jan 23, 2024
Sep 12, 2023
Sep 12, 2023
Sep 12, 2023
Jan 22, 2024
Jan 22, 2024
Jan 23, 2024
Feb 13, 2024
Sep 18, 2023

Repository files navigation

tbdex-js

codecov OpenSSF Scorecard

This repo contains 3 npm packages:

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 this config which will only checkout the files relevant to tbdex-js

git -C tbdex sparse-checkout set hosted

node

This project is using node v20.3.0. You can verify your node and npm installation via the terminal:

$ node --version
v20.3.0

If you don't have node installed, Feel free to choose whichever approach you feel the most comfortable with. If you don't have a preferred installation method, we recommend using nvm (aka node version manager). nvm allows you to install and use different versions of node. It can be installed by running brew install nvm (assuming that you have homebrew)

Once you have installed nvm, install the desired node version with nvm install vX.Y.Z. After installation, you may run nvm use to automatically tell nvm which node version to use (this will be picked up from the target version noted in .nvmrc):

$> nvm use
Found '/Users/.../TBD54566975/tbdex-js/packages/protocol/.nvmrc' with version <v20.3.0>
Now using node v20.3.0 (npm v9.6.7)

If you don't have pnpm installed, choose whichever approach you feel most comfortable with here

Note

it's possible that this project may work with npm as well but it's not guaranteed.

Running Tests

Note

Make sure you have all the prerequisites

  1. clone the repo and cd into the project directory
  2. Install all project dependencies by pnpm install
  3. Build all workspace projects in this repo by running npm run build
  4. run tests using pnpm test:node to run tests within a nodejs runtime
  5. 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

Changesets

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

Upon opening a Pull Request, the changeset-bot will automatically comment (example) on the PR with a reminder & recommendations for managing the changeset for the given changes.

Prior to merging your branch into main, and given you have relevant semantic versioning changes, then you should run pnpm changeset locally. The CLI tool will walk you through a set of steps for you to define the semantic changes. This will create a randomly-named (and funnily-named) markdown file within the .changeset/ directory. For example, see the .changeset/sixty-tables-cheat.md file on this PR. There is an analogy to staging a commit (using git add) for these markdown files, in that, they exist so that the developer can codify the semantic changes made but they don't actually update the semantic version.

You can stop here! It is recommended to merge your branch into main with the .changeset/*.md files, at which point, the Changeset GitHub Action will automatically pick up those changes and open a PR to automate the pnpm changeset version execution. For example, see this PR. This command will do two things: update the version numbers in the relevant package.json files & also aggregate Summary notes into the relevant CHANGELOG.md files. In keeping with the staged commit analogy, this is akin to the actual commit.

Cutting Releases

When a changeset PR is merged to main we will automatically create a GitHub release using the workflow Create GH Release.

Note

This is done by detecting the merged PR branch name: changeset-release/main.

Also, by creating the GH release, the packages will be automatically published to npm. So this way the engineer can simply just merge the changeset PR and the new GH Release and packages version will be automagically published to npm!

Steps for a new release publish

Recap of the above changesets, plus the release process:

  1. Open a PR
  2. changeset-bot will automatically comment on the PR with a reminder & recommendations for semver
  3. Run pnpm changeset locally and push changes (.changet/*.md)
  4. Merge PR into main
  5. Profit from the release automation:

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