We are excited to announce TypeScript support in the JavaScript SDK! TypeScript provides myriad improvements to the JavaScript development process. In this article, we will show you how Algorand’s TypeScript support can supercharge your development experience and what it will mean for your existing projects.

What is TypeScript?

Most simply, TypeScript is a superset of JavaScript that includes static type checking and helpful object-oriented programming structures, such as enums, interfaces, and abstract classes. Don’t worry though, your JavaScript code is safe: the TypeScript compiler compiles TypeScript files back into pure JavaScript code that can be run anywhere JavaScript can.

TypeScript provides many advantages over vanilla JavaScript. Similar to other programming languages that utilize static type checking, TypeScript saves you time by catching common errors before runtime, warning you, for instance, if a function’s parameter types differ from the types of passed in values. Situations such as incorrectly passing strings to class constructors that only accept numbers or vice versa, quickly become things of the past.

Plus, the type definitions and included auxiliary structural utilities can encourage self-documenting code and improve readability. No more searching to determine whether that ambiguous parameter named “binary” is a Buffer or Uint8Array. And since TypeScript code is fully-typed, modern IDEs that support the TypeScript language server display intelligent autocompletions and inline type warnings.

Please refer to the TypeScript website for more information on the TypeScript language. I highly recommend TypeScript’s handbook if you are hoping to learn the basics.

What’s Changed?

For the most part, the only change is that the JavaScript SDK has been rewritten in TypeScript. Code was migrated with backwards compatibility in mind, so the SDK should be functionally equivalent to its JavaScript counterpart. Projects that import the JavaScript SDK will continue working with no major changes. This backwards compatibility requirement did limit optimal type definitions in certain places, but we hope to make types more consistent in the future.

There were some other notable changes:

• Build steps were updated — projects using webpack or rollup.js can take advantage of tree-shaking to reduce their JavaScript bundle size.
• Several bugs were caught during the migration, mainly as a result of TypeScript’s static type checking.

How does TypeScript migration affect my projects?

To reiterate, the TypeScript migration should not be functionally different than before; projects that worked with the pure JavaScript SDK will still work with the TypeScript adaptation.

Node.js Projects

Though Node.js projects will not benefit from the static type checking aspect of TypeScript, supported IDEs (VSCode included) will still provide intelligent autocompletions and improved documentation on hover.

For the most part, you won’t need to opt-in or edit any configurations to receive these benefits – just make sure to update to the latest SDK version when the TypeScript release becomes available. However, you should check whether your editor requires an extension for TypeScript support.

TypeScript Projects

On top of the improvements listed above in the Node.js section, TypeScript projects will benefit from the typical TypeScript features, such as static type checking and warnings when code is not used as intended.

For your convenience, we have exported common types, such as transaction object structures, account objects, suggested parameters, and more. We recommend projects take advantage of these types for the optimal TypeScript experience.

import * as algosdk from 'algosdk';

const suggestedParams: algosdk.SuggestedParams = {
  ...
}

Similar to Node.js projects, there shouldn’t be any additional steps to integrate TypeScript into your project – just update to the latest version when it becomes available.

After updating, you may observe TypeScript warnings caused by incorrect implementations that previously went unnoticed, such as passing a number to a function that should only allow strings. Such warnings merely indicate conflicting types and fixing them should prove trivial.

Web Projects

Unfortunately, web projects that include the Algorand SDK in an HTML script tag will not benefit from the TypeScript migration, but code will still work exactly as before. This is because most editors won’t know that window.algosdk belongs to the Algorand SDK script tag, nor be able to import the associated type declaration files that are needed for intelligent autocompletions.

However, if it is a web project that takes advantage of NPM modules, and therefore is eventually bundled before being used in the browser, the project, for the purposes of this article, falls under the category of a Node.js project and can take advantage of all of the improvements outlined in the section above.