itwinjs-core: the Rush monorepo behind the iTwin.js digital twin libraries

One repository publishes every iTwin.js npm package

itwinjs-core is a monorepo holding the source for multiple iTwin.js npm packages, and the iTwin.js project is described as an open source library for creating, querying, modifying and displaying infrastructure digital twins. The feature list gives the scope: building twins of assets or projects, aggregating engineering models, reality data, geographic information systems, IoT data and other standard formats, visualising data and engineering changes in 3D and 4D, and analysing that data across platforms. The intended users are the engineers and teams behind Bentley-centred infrastructure tooling, BIM workflows and asset management products. What they are adopting is not an application but a library set, and the practical question is therefore less about what it does and more about how the packages are built, versioned and debugged, which is where most of the interesting details sit.

Rush owns the dependency graph, and npm is locked out of the root

The build is driven by Rush, and the root package.json goes out of its way to stop anyone bypassing it. Its scripts do not run the work, they print a reminder:

  "scripts": {
    "build": "echo NOTE: use 'rush build' instead",
    "clean": "echo NOTE: use 'rush clean' instead",

The install path is guarded harder, because an npm install at the root would silently produce a broken tree:

    "preinstall": "echo ERROR: use 'rush install' instead && exit 1"

The root package is private and never published, and dependencies and devDependencies are deliberately empty there, since each package declares its own. Rush manages a shared set of common dependencies, and each package gets its own node_modules directory containing symbolic links to them. That is the mechanism behind the repo layout: the top-level directories are not arbitrary groupings, they are Rush workspace groups, and rush.json is the complete list of packages while Versioning.md holds the package and API versioning policy.

Four commands take you from clone to a green test run

The developer quick start is four steps, and the prerequisites are pinned hard. Node must be an installation of the latest security patch of Node 24, and the Node installation is expected to bring npm with it, but pnpm is named as the required package manager because it is more performant and monorepo friendly, with corepack enable pnpm given as the recommended way to install it. Rush itself is installed globally with npm install -g @microsoft/rush. TypeScript arrives as a devDependency through rush install rather than being installed by hand, and Visual Studio Code is optional even though the repository structure is tuned for it. The build sequence itself is short: clone the repository with git clone https://github.com/iTwin/itwinjs-core.git, then run rush install, then rush build, and finally rush cover to run the tests. Longer explanations live in CONTRIBUTING.md, which covers editing workflows, debugging tests and contribution standards.

display-test-app is the instrument for driving the APIs by hand

The most useful thing in the repository for a working engineer is the display-test-app, a desktop-style test application built as part of the monorepo. The README describes it as the easiest way to exercise iTwin.js APIs directly against the source code in the repository, and gives three concrete uses: reproducing a bug, demonstrating a feature gap, and testing a local change. The reason it beats an online sandbox is structural. It runs against the code in your working tree rather than a published release, so a fix you just made is the code under test, and because it is an Electron app it can also exercise desktop-only workflows such as editing. The developer quick start builds it along with everything else, and the display-test-app README covers how to run it and how to open an iModel.

Key-ins and a repro agent for driving the display test app

Inside the display test app there is a mechanism called a key-in, described as a convenient, self-contained way to invoke whatever iTwin.js API you want to test, with a step-by-step guide and a skeletal example in the display-test-app README. In practice it turns the app into a console for the library: instead of writing a frontend to reach an API, you trigger it and watch what happens. The README also mentions a DTA repro agent at .github/agents/dta-repro.agent.md that specialises in scaffolding minimal reproductions in display-test-app, aimed at people working with AI coding agents. Both pieces point the same way. This is a large library where the interesting failures live in the interaction between rendering, data and native layers, and the project has invested in small, direct ways to reach a single API rather than in heavier integration test harnesses.

The directory layout encodes how the library is divided

The top-level entries describe the architecture more honestly than the feature list does. There is core, domains, presentation, editor, ui, utils, tools and extensions, plus common for the shared configuration Rush uses, full-stack-tests for end-to-end coverage, example-code for samples, test-apps for the display test app, and docs for the learning material, including a supported platforms page. Two structural points follow. First, the layering is explicit, with core sitting below the presentation and editor layers and extensions sitting outside, which is the usual way a rendering library keeps third-party add-ons from reaching into internals. Second, the platform question is answered in a document rather than in the code, so a project targeting a platform outside the supported list needs to read docs/learning/SupportedPlatforms.md before it starts. The repository also carries an AGENTS.md file and a Steering.md file at the root, which indicates that conventions are documented for tooling and for human review.

MIT terms with a Bentley copyright, and a 5.14.x release train

The licensing is straightforward at the package level: the root package.json sets the licence to MIT, and the README states that copyright rests with Bentley Systems, Incorporated, with the full terms in LICENSE.md. The README also points out that other samples are hosted on developer.bentley.com, which is where the iTwin Platform and broader sample set live, while the Quick Start in this repository links to a 3D viewer sample built on the packages published here. On maintenance, the last push was on 2026-10-20, so the repository is receiving work continuously. The release naming shows the shape of that work: release/5.14.0 on 2026-10-02, release/5.14.2 on 2026-10-06 and release/5.14.3 on 2026-10-12, that is a patch line shipping several times within two weeks. Consumers should note that the numbering follows a monorepo-wide line rather than independent package versions, and Versioning.md is the file that explains how package and API versions relate.

Editorial conclusion

itwinjs-core fits teams already invested in Bentley infrastructure data who need the iTwin.js packages, want to build them from source with a consistent dependency graph, or need a way to reproduce a rendering or data issue against a working tree rather than a published release. It does not fit a project that wants a single small npm install for a 3D viewer, or a team unwilling to take on a Rush monorepo workflow. Before adopting it, check the Node 24 requirement and the supported platform list, and read the display-test-app README to see how far the in-repo debugging path covers the problem you have.

Frequently asked questions

Official sources

1. iTwin/itwinjs-core on GitHub
2. License: MIT
3. Project website
4. README
5. Releases