SHR Development Environment

The SHR tool chain is the combination of several different Node.js modules, orchestrated together in the shr-cli project. For users who simply wish to invoke the tool chain, only shr-cli is needed, as it declares its dependencies and they can easily be installed via yarn.

Developers who wish to work on individual components of the tool chain, however, and to see how they work in the context of shr-cli will need to clone all of the individual components and "link" them together. This page provides brief instructions on how to do so.

Clone shr-* projects

We recommend you create a new folder to contain the SHR-related tools. For this documentation, we will call that folder standardhealth:

mkdir ~/dev/standardhealth

From within the standardhealth folder, you should clone each of the SHR packages needed by shr-cli (including shr-cli):

cd ~/dev/standardhealth
git clone https://github.com/standardhealth/shr-cli.git
git clone https://github.com/standardhealth/shr-es6-export.git
git clone https://github.com/standardhealth/shr-expand.git
git clone https://github.com/standardhealth/shr-fhir-export.git
git clone https://github.com/standardhealth/shr-json-javadoc.git
git clone https://github.com/standardhealth/shr-json-schema-export.git
git clone https://github.com/standardhealth/shr-models.git
git clone https://github.com/standardhealth/shr-test-helpers.git
git clone https://github.com/standardhealth/shr-text-import.git
git clone https://github.com/standardhealth/shr_spec.git

Build shr-* projects

The shr-* projects declare dependencies in their respective package.json files. To run these projects, we need to install the dependencies using yarn.

One approach is to cd into each folder and invoke yarn. Since this can be cumbersome, however, we've built a script that will do it for you. This script lives in shr-cli. To use it:

cd ~/dev/standardhealth/shr-cli
./rebuild-all

Link shr-* projects

The projects are now cloned and built, but completely independent from each other. Each has pulled down its own dependencies from the NPM registry. This is fine if you only want to test the project independently (using unit tests), but doesn't work well if you want to test it in the context of shr-cli (since shr-cli references the NPM-published versions of shr-*, not your local versions).

To test local shr-* project changes using shr-cli, you must "link" the projects together using yarn link. This makes dependencies between shr-* projects use the local versions of the code rather than the NPM-published versions.

For example, if shr-cli depends on shr-fhir-export (which it does), then shr-cli/node_modules/shr-fhir-export would normally contain a copy of the shr-fhir-export code that was downloaded from NPM. After using yarn link, however, shr-cli/node_modules/shr-fhir-export will actually be a symlink to your local shr-fhir-export code. This is what allows you to test your local changes in the context of shr-cli.

Normally, you would need to "register" each shr-* project first, then actually "link" to each affected dependency in each project. This is cumbersome, so we've developed a script for this as well:

cd ~/dev/standardhealth/shr-cli
./yarn-link-all

NOTE: For best results, you should always ./rebuild-all before linking.

Run shr-cli

Now you should be able to run shr-cli as normal, but it will be referencing all of your local code:

cd ~/dev/standardhealth/shr-cli
node . ../shr_spec/spec

Unlink shr-* projects

You may not always want your projects linked together. For example, you may want to test that a version actually works correctly using all of the published (non-linked) dependencies. In addition, if things seem to get wacky, it can help to unlink your projects and relink them again. Once again, we have a script for this:

cd ~/dev/standardhealth/shr-cli
./yarn-unlink-all
./rebuild-all

NOTE: As shown above, you always want to rebuild after unlinking, as unlinking will leave your node_modules in an unstable state.

Switching Branches

One strategy we often employ is to use the same branch name across multiple shr-* projects when they depend on changes in each other. In these cases, we may want matching foo branches on as many of the shr-* projects that have foo branches. We've created a script to make this easy:

cd ~/dev/standardhealth/shr-cli
./switch-all-branches foo

NOTE: This will only switch branches on projects that have a foo branch. Projects without a foo branch will remain on the same branch they already were on. Also note that if a branch added new dependencies, you may need to rebuild-all before it works properly.

For more information regarding advanced branch management functionality, run: ./switch-all-branches -h

Pulling Latest Changes

In order to get the latest changes from the GitHub repository, the following script can be used (to avoid having to cd to every directory and run the command randomly):

cd ~/dev/standardhealth/shr-cli
./pull-all