iTwin.js 3.0 Release Candidate

[calebmshafer]

Hey everyone!

We are excited to announce the Release Candidate for iTwin.js 3.0! It has been almost a year and a half since our last major release and we're excited to get feedback from the community on all of the new features and enhancements in this latest version.

This post will provide a quick overview of the goals we set out to achieve for this release and point to what is included in the release candidate. In addition, we have been working on a set of release notes that will help guide you through the various changes made and provide an upgrade path to make the transition easier.

Goals of the release

A few high-level objectives guided the changes made during the 3.0 release to provide a strong foundation for the exciting features to come during this 3.x generation.

1. Stabilize our core APIs around Web and Desktop visualization.
   • Clean up some of the current APIs and promote others to a public release tag.
2. Set the stage for Editing with an initial API that lays the groundwork for all of the enhancements to come within the 3.x generation.
3. Enhance the support for the iTwin Platform and provide better flexibility for different client implementations and authorization providers/workflows
4. Update our iTwin App UI to work more seamlessly with iTwinUI.

What's included?

This release has many different pieces to it, including many packages which have moved to different repositories and have been renamed. The full guide to all of the renames and updates is available in our release notes (Note: they are a work in progress so any feedback would be appreciated!).

A few major changes are called out below, as they are not mentioned or may not be clear in the release notes at the moment.

• The former imodeljs repository and many of the packages it contained are now available at itwinjs-core. The old imodeljs GitHub Organization is being phased out in favor of iTwin.
• All packages in the iTwin.js 3.0 release the @itwin npm scope instead of @bentley
• Release candidate version of the iTwin Viewer is available accompanied by a new deployment of the "general-purpose-imodeljs-backend" (now just referred to as "visualization") that supports iTwin.js 3.0
• New client packages for the iModels, Reality Data and Projects iTwin Platform APIs are available in the linked repositories. They correspond with a new set of OAuth2.0 scopes that need to be registered as well.

How do I try it out?

If you have an existing application built on iTwin.js 2.x, head over to our release notes and try out our new codemod tool to make migration easy!

If you're starting fresh, try out the release candidate version of our iTwin Viewer by running the following command:

npx create-react-app@latest web-viewer-3 --template @itwin/web-viewer@next --scripts-version @bentley/react-scripts

Known issues

As this is a release candidate there are a few issues to fix before the official release. This is not a comprehensive list but highlights some of the larger items you may run into when testing out the release candidate.

iTwin.js Core

• The @bentley/itwin-client package is still a required peer dependency of a few packages. This package will be fully removed prior to the official release.

iTwin Viewer

• As of create-react-app@5, global installations of create-react-app are discouraged and can cause issues when bootstrapping a new app from a template. We recommend you uninstall the package using npm uninstall -g create-react-app or yarn global remove create-react-app to ensure that npx always uses the latest version.
• As of create-react-app@5, many users have reported a fatal runtime error, Uncaught ReferenceError: process is not defined. This can be resolved by pinning down the version of react-error-overlay to 6.0.9. Please see the following issue for more information, create-react-app/issues/11773.
• Missing feature:
  • The following features/widgets that are a part of the default iTwin Viewer are still under development and will be added back as they're ready.
    - [x] Tree Widget
    - [x] Property Grid

[kckst8]

Be sure to have prereqs installed prior to attempting to install the iTwin Viewer template.

[ashish-srivastava-dev]

When I am upgrading to v3, which packages I should use for Tree Widget and Property Grid?

[ashish-srivastava-dev]

Should I continue to use their v2 compatible packages (e.g. @bentley/tree-widget-react) along with other v3 packages?

[aruniverse]

No those are incompatible. I'm working on getting an updated 3.0 version of those packages and will update once available.

[aruniverse]

@ashish-srivastava-dev please see below, #2942 (comment)

[ashish-srivastava-dev]

Thanks for the update.

[aruniverse]

The bentley scoped tree-widget-react and property-grid-react pkg have been converted to use the 3.0 rc, and are now being published under the itwin scope. See:
https://www.npmjs.com/package/@itwin/tree-widget-react
https://www.npmjs.com/package/@itwin/property-grid-react

You can bump the dep on itwin/web-viewer-react to version 2.0.0-dev.21 for those widgets to be automatically pulled in. Please note there was a breaking change between 2.0.0-dev.20 and -dev.21 where we renamed the authConfig prop to authClient. Please refer to our changelog, https://github.com/iTwin/viewer/blob/next/NextVersion.md