Get Started!

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.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.

2. Get the code

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

  1. Open Terminal or a Command Prompt.
  2. In the terminal, run the following command: npx create-react-app your-app-name --template @itwin/web-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
npx create-react-app your-app-name --template @itwin/web-viewer --scripts-version @bentley/react-scripts

3. Register an Application

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

Click the Register Application button to automatically register a client for this quick start. You can find registered application in My apps page.

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 http://localhost:3000/signin-callback
  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.

4. 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 to automatically create an iModel for use with this quick start. You can find created iModel in My iModels page.

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.

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 or any other SPA app and iModel from your account.

  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_AUTH_CLIENT_REDIRECT_URI: Enter the Redirect URI for the client you registered during the Register a Client step
    • IMJS_AUTH_CLIENT_LOGOUT_URI: Enter the Post Logout Redirect URI for the client you registered during the Register a Client step
    • IMJS_AUTH_CLIENT_SCOPES: Enter the Scopes 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.

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.