Code intelligence improvements

Code intelligence improvements

Together with everything else that is spice and nice in Fonto 8, our latest SDK will include TypeScript support and a lot more code intelligence than before. In terms of stability, velocity and developer quality of life this is our biggest update ever!

Even if you don’t want to use TypeScript, the new update instantly provides a wealth of code intelligence that you would otherwise have to find in our API docs. If you do upgrade your files to TypeScript, one by one if you choose, you will get even better squiggles and warnings in case you’re about to make a bug. We expect velocity gains and reduced bugs for all our partners.

Concretely;

  • An IDE like Visual Studio Code will make automatic import suggestions for any API you want to use.
  • For any class method or function call, a tooltip will tell you everything about it, including its description, the arguments it expects, and what it returns back to you. If you’re about to make a mistake, a squiggle will underline this for you.
  • Not sure what properties live on an object, or which ones are expected? Auto-complete will tell you.
  • Typing is already applied to Fonto’s own SDK, and you can add it to your own configuration code.

The only thing you need to do for this upgrade is make sure your version of Fonto’s development tools is up to date, and install the new SDK as normal.

npm install -g @fontoxml/fontoxml-development-tools@latest
fdt editor upgrade --version 8.0.0

Fonto takes care of the configuration files that point your IDE in the right direction. Any IDE that supports TypeScript (all the front-end oriented ones we could find do) will probably pick up on it automatically. To ensure compatibility with Fonto’s tools, install the supported TypeScript version in your project;

npm install typescript@4.3.4 --save-dev

To find out if your preferred IDE supports TypeScript or requires additional plugins, please refer to its documentation.

You may find you don’t even have to use TypeScript to start benefiting from our typed platform. An IDE like Visual Studio Code will provide (some) code intelligence for regular JavaScript files too. You can use TypeScript and JavaScript files alongside one another, so it is possible to upgrade your configuration as much as you want to, when you want to.

TypeScript files still close the door on bugs better than anything else. For our own teams it worked well to rename all JavaScript files but type only the ones we were touching during development, and start any new files as .ts or .tsx. The most valuable quality of life improvement comes from upgrading the top files that are referenced the most.

What is TypeScript?

JavaScript is dynamically typed. Essentially nothing prevents you from putting a square peg into a round hole, or vice versa. Without great discipline and knowledge of a code base, this is a common source of bugs. Untyped code is harder to read, easier to break, and costlier to maintain.

The following JavaScript code produces an unexpected outcome, but only when the function is actually executed. If the function were tied to a button or other, and your application is full of buttons, it becomes hard to know exactly how full of bugs an application is:

function sumOfNumbers (value, addition) {
  return value + addition;
}

sumOfNumbers(42, 'apple');

TypeScript is an extra language layer with which you can describe what the shapes of pegs and holes are. It enables your code editor to warn when you’re about to make a combination that doesn’t fit.

The same code could be rewritten to TypeScript, and lets the code author see which mistake they are making on the last line. The code editor gives feedback without even having to run the function, and it can do so for every button, not just the ones that happen to come up in a test. This is hugely valuable for ensuring the stability of your configuration, without investing the time it takes to test all of its features.

function sumOfNumbers (value: number, addition: number) {
  return value + addition;
}

sumOfNumbers(42, 'apple');
                 ^^^^^^^ "apple" is not a number

We have been using TypeScript at Fonto for the last year and we crunched the numbers. We estimate that the number of issues that are severe enough to warrant a patch release of Fonto are reduced by as much as 25% by using TypeScript alone!

How does Fonto use TypeScript?

We’ve typed our public API surface as much as we could. The surface is huge, but we did a pretty good job. Thanks to our API documentation most types already had a pretty good description. The APIs that remain untyped are effectively any or unknown types, meaning they will accept any peg that you’d want to put into that hole. Fonto will improve its typing again with every release, as part of normal maintenance work.

As part of those improvements we’ll introduce new types and interfaces to Fonto’s API surface. We’ll focus on the types that are currently hard to infer, or the ones  that make typing a whole lot easier.

Take for example the ModalProps type. It is designed to quickly type all of the props received by a modal component. Because a part of those props are determined by Fonto, and another part is determined by configuration, a generic parameter helps to type the combination of them.

const MyModal: FunctionComponent<ModalProps> = ({
  cancelModal,
  submitModal
}) => {
  ...
};

Your IDE will now tell you what shape cancelModal and submitModal are. To give you a hint; their description was previously only found in our How to create a custom modal guide.

Fonto’s code base is large, and we’ve fortunately been able to type our platform code to a large degree and in a short amount of time. Most of the APIs that your configuration interacts with will therefore already come with the intelligence that you would expect. However, Fonto will continuously evolve the platform and improve typing in other areas. If you find that any of the code intelligence you’re receiving is lacking, wrong, or unclear, we encourage you to let us know via our support board.

We know that one of the points of improvement is that your code editor may suggest importing an API from a location that is not the documented import location. Before we had this type of code intelligence that would make it unstable code. However, to avoid affecting you with this Fonto commits to keeping the import paths that your IDE suggests stable – and when we fix this definitively, we will also automatically rewrite your configuration code to use the stable import paths again. In other words; we’re handling this for you.

How can I use the improved code intelligence?

The first step is to make sure your installation of Fonto’s development tools is up-to-date, and then upgrade to the latest SDK. These are the normal steps for any upgrade, find more information here.

In addition, install the TypeScript version compatible with Fonto’s tools in your project;

npm install typescript@4.3.4 --save-dev

From this point onwards import suggestions, better tooltips and autocompletion on options should work. As mentioned before you can continue to mix JavaScript with (hopefully more and more) TypeScript code, as you please. If you don’t want to change more code at this time that’s okay. Don’t even want all the new shinies? Simply remove tsconfig.json.

If you have existing configuration, our recommendation is to rename any JavaScript files to the TypeScript file extensions, write any new configuration or UI in TypeScript, and only add typing to an existing file if your other code interacts with it a lot. Any JavaScript file can be safely renamed to its TypeScript counterpart — JavaScript is valid TypeScript! Our build system too will automatically pick up on this, so there is no need to change your code imports. Renaming .js files to .ts (and .jsx to .tsx) lets Visual Studio Code display squiggles on your screen where TypeScript has someting to tell you – other IDE’s might not even need this.

There are a lot of resources online on how to do a bulk file rename, but most of them depend on commands that are available only for specific operating systems. I took a few minutes to write a bit of NodeJS that doesn’t care whether you are on Windows, Mac, or Linux. Whichever script you choose, always be sure to have the working state of code committed to version control before you perform a bulk action like the following;

# Start in your Editor configuration root folder
cd packages/
npx wvbe/change-file-extensions .js .ts
npx wvbe/change-file-extensions .jsx .tsx

If you happen to have JavaScript files in your assets/ folder, or you’re serving 3rd party library files, you may want to avoid renaming those (or revert them after a bulk rename).

For new configurations, the code that our development tools generate for you will be in TypeScript right away. This makes it easy to continue using it throughout — but at all times you could also leave something untyped if that’s your preference. Normal JavaScript is valid as TypeScript, too!

Now it’s just a matter of using TypeScript in the way that works best for you. Once Fonto 8.0 drops we are super excited to hear about your experiences! Drop us a line!

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top