Getting Started

Quick Start tutorial

Introduction


This quick start is intended to help you get started with using iTwin Platform visualization components. In this walk-through, you will be introduced to the iTwin Viewer, a customizable viewer that offers basic tooling and widgets for viewing an infrastructure digital twin and can be further extended with iTwin.js extensions.

By the end of this walk-through, you will be able to build and run a web application for viewing an infrastructure digital twin (iTwin).

Info


Skill level:

Basic

Duration:

30 minutes

1. Set up your environment


Before you start this walk-through, you will need to download and install the following software on your machine.

1.1 Required materials


Node.js (12.x LTS version)

This tool provides the backend JavaScript runtime necessary for your computer to read and render code appropriately. It also allows you to run NPM command line (required for every iTwin project).

Git

This is the source code control system for the iTwin repositories.

1.1 Required materials


1.2 Suggested materials


Google Chrome

This software can help you to develop and debug frontend JavaScript problems.

Visual Studio Code

This is our recommended editor and debugger tool for developing iTwin.js applications. It is free, open source and includes a GUI for working with GIT.

1.2 Suggested materials


2. Register an Application


To build an application on the iTwin Platform, you will need to register a client.

Click the Register Application button on the right-hand side to automatically register a client for this quick start.

Optional: Manual Application registration process


To manually register a client:

  1. Go to https://developer.bentley.com
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My Apps page
  4. Click the Register New button
  5. Give your application a Name
  6. Select the Visualization API
  7. Select application type SPA (Single Page Web Application)
  8. Enter Redirect URL
    • For this tutorial use https://localhost:3000
  9. Leave post logout redirect URIs empty.
  10. Click the Save button
Note the Client ID that is generated during the registration process. You will need this in a later step.

2. Register an Application


3. Create an iModel


To view your engineering design content, you will first need to synchronize your design files into an iModel. An iModel is a distributed relational database holding information about an infrastructure asset defined in a common schema. To learn more, click here.

Click the Create iModel button on the right-hand side to automatically create an iModel for use with this quick start.

Optional: Manual iModel creation process


To manually create an iModel using your own engineering design files (DGN, RVT, SP3D, etc):

  1. Go to https://developer.bentley.com
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My iModels page
  4. Click the Create button
  5. Give your iModel a name
  6. Select Create iModel from Local File and provide the needed file.
    • If you don’t have your own engineering design files, you can select Create iModel from Bentley Template and choose the Retail Building Sample template
  7. Click the Save button and wait until your iModel is created
Note that after completing this step, you will be provided with both a ContextID (i.e. ProjectId) and an iModelID which will be required in a later step.

3. Create an iModel


4. Get the code


The iTwin Viewer is available on GitHub at link. To download the iTwin Viewer code:

  1. Open a Node.js command prompt window
  2. In the terminal, run the following command: npx create-react-app your-app-name --template @bentley/itwin-viewer --scripts-version @bentley/react-scripts
    • This will generate a new application based on the iTwin Viewer React component.
    • By default, the viewer will be stored in a directory called your-app-name

4. Get the code


npx create-react-app your-app-name --template @bentley/itwin-viewer --scripts-version @bentley/react-scripts

5. Run the code


After you have successfully downloaded the code, you are ready to run the sample. To run the sample:

Note: the following instructions show how to run the code using VS Code, but the same commands can be completed in a terminal.
  1. Launch Visual Studio Code
  2. Click File > Open Folder and open the your-app-name directory that was created in the previous step.

Next, you will need to configure the application with the client and iModel information that you created in the previous steps.

  1. Open the .env file
  2. Enter the appropriate values for:
    • IMJS_AUTH_CLIENT_CLIENT_ID: Enter the ClientID for the client you registered during the Register a Client step
    • IMJS_CONTEXT_ID: Enter the ContextID that was generated during the Create an iModel step
    • IMJS_IMODEL_ID: Enter the iModelID that was generated during the Create an iModel step
  3. Open a terminal from the menu bar View > Terminal.
  4. In the terminal window, enter npm start. This will serve the application with live reloading.
Note: You can add/update/remove files as needed. If running `npm start` while making changes, your application will automatically recompile and reload.

Congratulations, running npm start should launch a web browser and display your iModel in the iTwin Viewer Starter App. If you use your own file, this may take a few minutes to load depending on the file size you used.

If the iTwin Viewer does not automatically open, you can open a browser and load the URL https://localhost:3000.

Continue learning


Congratulations for the completion of your first viewer app! You’ve now know a lot on the subject, but there’s still possibilities to learn more to unleash the platform capabilities.

Customizing the iTwin Viewer - “The Basics”

This tutorial will take you through the first steps of customizing your iTwin Web Viewer. First you will learn how to add a new user interface component. Later you will customize that component to change the background color of your viewer.

Adding showcase widgets to your iTwin Viewer

This tutorial will take widgets from the sample showcase and add them into your iTwin Viewer using the uiProviders prop.

More resources that you may like


Create React App

Set up a modern web app by running one command.

iTwin Viewer React

The iTwin Viewer is a configurable iTwin.js viewer that offers basic tooling and widgets out-of-the-box and can be further extended through the use of iTwin.js extensions. This package contains the Viewer as a React component and some additional Typescript API’s.

iTwin Viewer Create React App Template

This is a template for applications that are based on the iTwin Viewer for Create React App.

Bentley React Scripts

This is the iTwin.js fork of react-scripts.