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.

Node.js (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.

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
BASH
npx create-react-app your-app-name --template @itwin/web-viewer --scripts-version @bentley/react-scripts

3. Register an Application

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to use the iTwin Viewer with the iModel you will generate next.

Once generated, you will be shown a few lines of code under the button. You will need to copy them in the .env file from the application folder downloaded in the previous step.

  • IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
  • IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. Displayed on application details page as one of Redirect URIs.
  • IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
  • IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Make sure that your application is associated with Visualization API and has openid email profile organization itwinjs scopes enabled.

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

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.

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.

Requires you to sign in. Will automatically generate a sample iModel from Retail Building Sample Bentley template that is required to complete this tutorial. This might take several minutes. You will be able to manage your iModel from your My iModels page.

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

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.