Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
iTwin.js is an open source platform for creating, querying, modifying, and displaying Infrastructure Digital Twins.
If you have questions, or wish to contribute to iTwin.js, see our Contributing guide.
This repository is a monorepo that holds the source code to multiple iTwin.js npm packages. It is built using Rush.
See rush.json for the complete list of packages.
Each package has its own node_modules directory that contains symbolic links to common dependencies managed by Rush.
- Git
- Node: an installation of the latest security patch of Node 12. The Node installation also includes the npm package manager.
- Rush: to install
npm install -g @microsoft/rush - TypeScript: this is listed as a devDependency, so if you're building it from source, you will get it with
rush install. - Visual Studio Code: an optional dependency, but the repository structure is optimized for its use
See supported platforms for further information.
- Clone repository (first time) with
git cloneor pull updates to the repository (subsequent times) withgit pull - Install dependencies:
rush install - Clean:
rush clean - Rebuild source:
rush rebuild - Run tests:
rush test
The -v option for rush is short for --verbose which results in a more verbose command.
The above commands iterate and perform their action against each package in the monorepo.
For incremental builds, the rush build command can be used to only build packages that have changes versus rush rebuild which always rebuilds all packages.
Note: It is a good idea to
rush installafter eachgit pullas dependencies may have changed.
- Make source code changes on a new Git branch
- Ensure unit tests pass when run locally:
rush test - Locally commit changes:
git commit(or use the Visual Studio Code user interface) - Repeat steps 1-3 until ready to push changes
- Add changelog entry (which could potentially cover several commits):
rush change - Follow prompts to enter a change description or press ENTER if the change does not warrant a changelog entry. If multiple packages have changed, multiple sets of prompts will be presented. If the changes are only to non-published packages (like display-test-app), then
rush changewill indicate that a changelog entry is not needed. - Completing the
rush changeprompts will cause new changelog entry JSON files to be created. - Check for API signature changes:
rush extract-api. This will update the signature files, located incommon/api. - Review any diffs to the API signature files in the
common/apidirectory to ensure they are compatible with the intended release of the package - Commit the changelog JSON files and any API signature updates.
- Publish changes on the branch and open a pull request.
If using the command line, steps 5 through 7 above can be completed in one step by running rushchange.bat from the imodeljs-core root directory.
Note: The CI build will break if changes are pushed without running
rush changeandrush extract-api(if the API was changed). The fix will be to complete steps 5 through 10.
Here is a sample changelog to demonstrate the level of detail expected.
The version numbers of internal dependencies should not be manually edited. These will be automatically updated by the overall version bump workflow. Note that the packages are published by CI builds only.
Use these instructions to update dependencies and devDependencies on external packages (ones that live outside of this monorepo).
- Edit the appropriate
package.jsonfile to update the semantic version range - Run
rush checkto make sure that you are specifying consistent versions across the repository - Run
rush updateto make sure the newer version of the module specified in #1 is installed
- Build TypeDoc documentation for all packages:
rush docs - Build TypeDoc documentation for a single package:
cd core\backendand thennpm run docs