Version 8.3.0 release!

[na9da]

Introduction

Today we are releasing Terriajs version 8.3.0 which includes a few breaking changes:

• Upgrade to Typescript version 4.9.x
• Upgrade to Mobx version 6.9.x

👉 This might affect your map only if it has local model layer modifications like your own custom data provider (aka catalog items). Otherwise you can proceed like any other normal upgrade.

The rest of this post describes steps to upgrade your terriamap with local model layer modifications to terriajs version 8.3.0 and how to address some of the issue that might come up.

If you have any difficulty upgrading your application please feel free to use this thread or create a new discussion topic and our team will respond to it.

Upgrading a fork of terriamap with custom model layer changes

Basic steps

1. Ensure your terriamap is in sync with upstream.
2. Check package.json and make sure the version of terriajs is at least 8.3.0.
3. Run yarn run gulp sync-terriajs-dependencies from the command line.
   
   This synchronizes the dependencies of your map with that of terriajs library
4. Run yarn install to install the new dependencies.
5. Run yarn run gulp build to build the updated application.
   
   Do a quick scan of the build log for any typescript errors
6. Run yarn run start to start your local server.
7. Open http://localhost:3001 in your browser to view the application.

🎉 🚀 If all goes well, you should be able to see your app and add your datasets to the workbench without errors. If that's the case you can ignore the rest of this document.

🥼 Advanced scenario

After following the basic steps above and opening terriamap application in browser, if you see a blank screen instead of the app, chances are that you might need to update your local code modifications to make it consistent with mobx 6 changes.

💡 One way to discover the error causing the blank page is to use Firefox devtools with pause-on-exception option enabled like in the below screenshot. Then you can try and fix each issue one-by-one till your app loads succesfully.

🔧 Upgrading your local code changes to Mobx 6

Mobx has a detailed migration guide for upgrading to mobx 6 API which explains why this change is required. Please refer to it before reading the remaining sections.

To migrate your local code to mobx 6 we recommend you follow the below steps:

1. Run npx mobx-undecorate --keepDecorators --dir=lib/
   
   This will modify your local code inside the lib/ directory to make it consistent with mobx 6 changes.

2. Run git diff to view the changes made by the upgrade script.

3. The script might make the following changes to your code:

   • If your classes use mobx decorators like @observable, @computed or @action. It will add a line makeObservable(this) to the constructor of your class.

   • If your class does not already define a constructor, then it generates one and inserts a call to makeObservable(this).

     👉 Note: When mobx-undecorate makes this change, it cannot automatically determine the parameters of your constructor. So it'll generate a // TODO: [mobx-undecorate] verify the constructor arguments and the arguments of this automatically generated super call in your constructor. You'll have to check and make sure the constructor has the correct parameters in its signature and is also passing the correct arguments to the super() call.

   • If your class is a terriajs Catalog item. Then you will most like need to change the constructor as:

       import { ModelConstructorParameters } from "terriajs/lib/Models/Definition/Model";
     
       export default class MyCatalogItem extends TableMixin(
         UrlMixin(CreateModel(MyCatalogItemTraits))
       ) {
         constructor(...args: ModelConstructorParameters) { 
     
           super(...args);
           makeObservable(this).
     
           /// rest of the constructor code ...
         
         }
      }

4. Rebuild and reload your app in browser

Other upgrade issues

Fixing re-decoration of overridden methods

If you are overriding terria model layer methods like selectableDimensions that already have a mobx decoration or some trait value, you will need to use the new mobx @override decorator when overriding them. The @override decorator should be used in place of @observable, @computed or @action. Note that @override should only be used when overriding an existing mobx decorated method.

Example mobx error for this issue:

  Error: [MobX] Cannot apply '@computed to 'MyCatalogItem.prototype.selectableDimensions: The field is already decorated with '@computed. Re-decorating fields is not allowed. Use '@override' decorator for methods overridden by subclass. 

Fixing duplicate Mixin inheritance issues

You'll need these changes only if you have used mixins like TableMixin in your custom code. TableMixin already inherits from CatalogMemberMixin and MappableMixin. So you will need to remove these Mixins from your CatalogItem if you are explicitly adding them.

Example mobx error for this issue:

Error: [MobX] Cannot apply '@observable' to '_AccessControlMixin.prototype._accessType': The field is already decorated with '@observable'. Re-decorating fields is not allowed. Use '@override' decorator for methods overridden by subclass.