Getting Started With iModel.js

1. Get the Tools

Writing an iModel.js application requires the following software:

  • Node.js (latest 10.x or 12.x LTS version)
    • This provides the backend JavaScript runtime.
    • The installation also includes the npm command line tool.
  • Google Chrome
    • This is the preferred tool for developing and debugging frontend JavaScript.
  • Git
    • This is the source code control system for the iModel.js repositories.

Suggested Tools

The following tools are very helpful and highly suggested for working with iModel.js:

  • Visual Studio Code
    • This is the recommended editor and debugger for iModel.js applications.
    • VS Code also supplies a graphical user interface for working with Git.
    • The following VS Code extensions can also be quite helpful:

2. Register Yourself

To be able to view/read iModel data, you will need access to the iModelHub, which requires a Bentley user account.

Register here

Note: Skip to step 3, if you already have a Bentley User Account.

3. Register your Application

Once you have a Bentley User account, you will need to register the application you are about to create so it can access iModelHub.

Register Here

There are three types of apps you can register:

Web Application
An interactive application obtains information from an iModel and presents that information in a user interface.

Agent Application
iModel agents and services are apps that have no interactive user interface.

Desktop Application
An interactive application obtains information from an iModel and presents that information in a user interface. The app runs in Electron on the user's desktop.

4. Create a Sample Project

If you don’t already have an iModel, our registration process makes it easy to create a new project in our “iModel Test Drive” organization, populate it with content, and give access to other developers.​

You have a few options:

  • Bentley Example - Bentley supplied example content if you are just starting out. Simply select an example from the Project Registration page.

  • Local File - Most common formats are directly supported (.dgn, .dwg, .rvt, .imodel), for other formats, follow these steps to convert to a Snapshot iModel' (.bim) before proceeding to the Project Registration page below.

  • iTwin Synchronizer - If your development project requires a live digital twin. Download here, instructions here.

Register Project Here

5. Get the Sample Code

The samples are included in imodeljs-samples. For the complete list of samples see the readme.

Depending on your choice of application type from step 3, you should start out with one of the following:

Basic Viewport App
An example of an interactive application which demonstrates how to:

  • Embed an iModel.js viewport into your application to display graphical data.
  • Include built-in tools for view navigation such as Pan, Rotate, Zoom.

iModel Query Agent
An example of an agent application which demonstrates how to:

  • Listen to changes made to an iModel on the iModelHub.
  • Construct a 'Change Summary' of useful information.

  • TypeScript
    • iModel.js applications are written in TypeScript and then compiled to plain JavaScript.
  • Node Package Manager (npm)
    • npm is used to install and manage dependencies of an iModel.js application.
    • The npm command line and npm scripts are used to build and test iModel.js applications.


Please see the Community Resources page for the best places to get more help.

Last Updated: 13 June, 2024