AppUI

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.

About this Repository

This repository is a monorepo that holds the source code to multiple iTwin.js AppUI 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.

Prerequisites

Git
Node: an installation of the latest security patch of Node 18. 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.

Build Instructions

Clone repository (first time) with git clone or pull updates to the repository (subsequent times) with git pull
Install dependencies: rush install
- Check variant version with: rush install --variant core-3x (see variant for clarifications)
- (First time) After installation go to /full-stack-tests/ui and run npx playwright install
Clean: rush clean
Rebuild source: rush rebuild
Run tests: rush cover

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 install after each git pull as dependencies may have changed.

Source Code Edit Workflow

Make source code changes on a new Git branch
- Each packages supports npm start command to enter build in watch mode for easy validation along the test-apps.
Ensure unit tests pass when run locally: rush cover
- Each packages will generate a detailed coverage HTML report which can be accessed in ui/[package]/lib/cjs/test/coverage/lcov-report/index.html.
Ensure integration tests pass when run locally: See the related Readme
Ensure linting passes when run locally: rush lint / rush lint:fix
Ensure prettier passes when run locally: rush prettier / rush prettier:fix
Locally commit changes: git commit (or use the Visual Studio Code user interface)
Repeat steps 1-4 until ready to push changes
Check for API signature changes: rush extract-api. This will update the signature files, located in common/api. Note: before doing this, first do the following:
- Be sure that your branch is up to date with the target branch (i.e. git merge origin/master)
- Cleanup your build output: rush clean
- Rebuild the project: rush build
Review any diffs to the API signature files in the common/api directory to ensure they are compatible with the intended release of the package.
- If any differences are in packages not modified on this branch, revert the changes before committing.
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 the test-apps), then rush change will indicate that a changelog entry is not needed.
Completing the rush change prompts will cause new changelog entry JSON files to be created.
Add and commit the changelog JSON files and any API signature updates.
Add or edit the related section in the docs/changehistory/NextVersion.md file.
Publish changes on the branch and open a pull request.

If using the command line, steps 8 through 11 above can be completed in one step by running rushchange.bat from the root directory. Only use rushchange.bat if none of the changes require a changelog entry.

Note: The CI build will break if changes are pushed without running rush change and rush extract-api (if the API was changed). The fix will be to complete steps 6 through 11.

Here is a sample changelog to demonstrate the level of detail expected.

Updating dependencies/devDependencies on packages within the monorepo

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.

Updating dependencies/devDependencies on packages external to monorepo

Use these instructions to update dependencies and devDependencies on external packages (ones that live outside of this monorepo).

Edit the appropriate package.json file to update the semantic version range
Run rush check to make sure that you are specifying consistent versions across the repository
Run rush update to make sure the newer version of the module specified in #1 is installed

Note: Also see the variant info.

iTwin.js core 3.x compatibility

AppUI 4.0 version must keep compatibility with iTwin.js core version ^3.7.0 to facilitate migration, in order to do so, a rush variant has been created.

Validating code for the variant

Once we are clear with the changes we have, it is a good idea to validate that they work as expected in the variant test app, this will also be done in the CI pipeline.

Simply replace step 2 of the Build Instructions with:

Install dependencies: rush install --variant core-3x

and follow the same instructions for the build and coverage steps.

External dependencies check

The external dependencies must be updated in this variant with the following commands.

Run rush check --variant core-3x
Run rush update --variant core-3x

Other NPM Scripts

Build TypeDoc documentation for all packages: rush docs
Build TypeDoc documentation for a single package: cd ui\core-react and then npm run docs

iTwin/appui