Typescript saves a lot of development time, but is it worth an entire migrating process?

I got you whenever there is a project that should be migrated to another language, your inner voice is shaking and screaming: NO GOD! PLEASE NO!
It doesn’t care if you are at work and you have to do it, since coding is your job or you are struggling with this decision for months, but your private project would be a better one after the migration.

TypeScript is powerful and saves you a lot of time and frustrating debugging sessions. For large projects, you need a good reason to stay on JavaScript instead of migrating to Typescript. But exactly for this reason, the following method brings up a way out. It leaves you to have a few available options of convenience, and I know what I am talking about.

I am currently developing my next Udemy course on “How to make an Idle Web Game in plain old JavaScript!”.

My advice: if you don’t know what you are doing, then it would be better to

and leave this JavaScript Jungle!

But wait! Isn’t Typescript just…

… a superset of JavaScript, and this would mean we can easily migrate to?

That is right, and knowing this brings us to the conclusion that all JavaScript code is valid TypeScript code. Setting another one on top: the Typescript compiler isn’t useable in Typescript projects only. This little dude is like Stoner Stanley, he doesn’t care at all. At least about the ending of the file. Give him a *.js or a *.ts file and I bet he doesn’t even notice the difference…

Real talk: We can create hybrid projects (Yes TS checks in JS files) and the chance of not having to migrate is high. Instead of procrastinating on this decision, this guide will show you how easily you can profit from a TypeScript feature in plain JavaScript projects!

Feel the Type!

What I explained so far includes only the type system of TypeScript. JavaScript can’t just recognize those types. How should it even do it? If TypeScript is the superset, JavaScript is the basic edition and has only the basic types: boolean, null, undefined, number, string, and object. How to make this even possible then?

Annotations aren’t an option, because they are like calling a function with wrong arguments: invalid.

let x: number, y: number;

Therefore, the above line won’t help us at all, like ignorant people. But we can rely on our good old Doc, no not Doc McCoy or Doc Brown, I mean the JSDoc!

Relying on him means using the easiest way. Align the style of comments to JSDoc known Syntax. We can now type previously variables with the following statement:

/** @type {number} */ 
let x;
/** @type {number} */ 
let y;

Accessing the two variables means we can assign two numbers.

x = 23;
y = 23;

Ha! Problem solved, no more questions, your honor!

OBJECTION!

x = 'OBJECTION!'; 
y = true;

Unfortunately, assigning every other value doesn’t result in an error. Although there should be one. The two lines are assigning the wrong value types and are valid.

So Why am I explaining this all to you?!

The reason for having this valid code comes from the circumstance that TypeScript checks on types only in a TS project-based environment. A JavaScript environment is not worth the highness's attention until we put there some treats. Luckily, we can enable this type to check manually by adding just a line. Converting

/** @type {number} */ 
let x;
/** @type {number} */ 
let y;

to

//@ts-check/** @type {number} */
let x;
/** @type {number} */ 
let y;

by just adding //@ts-check above the JSDoc notated lines and you get the overall wise solution. Only the wisest would choose such a simple one. There are more keywords of JSDoc being supported by Typescript.

But wait! Ain’t nobody got time for manually putting the statement of //@ts-check into all files!

Configure your JavaScript Project

Instead, we are going to make it globally available and have to implement the line only once. So we create the file jsconfig.json. Yes, you heard right, this is the little brother of the tsconfig.json that tries to copy whatever the greater brother does for JavaScript projects.

{ 
  "include": ["./src/**/*.js"],
    "compilerOptions": {
        "checkJs": true,
    }
}

Want to exclude some files from the party and play the disco bouncer for the first time in your life? Either exclude the in jsconfig.json

{ 
  "include": ["./src/**/*.js"],
    "compilerOptions": {
        "checkJs": true,
    },
    "exclude": [
        "node_modules",
        "**/node_modules/*"
    ]
}

or go into the specific file and add:

//@ts-nocheck

Since TypeScript 3.7

Give me a number between 0 and 10! It is the 7, almost in 70% of cases, whenever I ask 70 people... This is magic and therefore TypeScript version 3.7 makes you can generate *.d.ts files out of type declarations, for which we use JSDoc comments. This means we can also type variables in libraries without migrating to TypeScript at all.

To do so, you need now the great brother tsconfig.json, although it is still a pure JavaScript project. But this operation isn’t an oneliner. All the following need to be included in your JSON file under the object of "compilerOptions" .

"allowJs" : "true": Consider even JavaScript files in the project and make type declarations. Default JavaScript files are ignored in TypeScript projects.
"declaration" : "true": Tell the compiler to explicitly create type declarations in form of *.d.ts files.
"emitDeclarationOnly": "true" : You only want to get type declarations and not a translation of the code.
"outDir": "./dist": Type declarations are not part of the source code. Therefore paste in your preferred directory.

Implementing them into your JSON-file will look like this:

{ 
  "include": ["./src/**/*.js"],
    "compilerOptions" : {
        "allowJs": true,
        "declaration": true,
        "emitDeclarationOnly":true,
        "outDir": "./dist"
    }
}

Not hacky enough?

If JSON file editing is not hacky enough, you’d start the compiler with specific options to get your desired result. Boot up your npx package manager and start with the explained options as starting parameters, like

$ npx tsc ./src/**/*.js --allowJs --declaration --emitDeclarationOnly --outDir ./dist

Takeaways

As you see procrastination on a decision and waiting until the end, doing it then in a rush isn’t very good. You would have used the time better researching and finding this article to preserve you to migrate your entire project, although your first thought of being mandatory. Instead, you found out how to profit from Typescript inside your JavaScript project!

Conclusion

So only a few steps are dividing you from creating a JavaScript/TypeScript hybrid. It doesn’t always need migration to Typescript. If you having a greater JavaScript project and aren’t willing to do the migrating limbo, then start with implementing type-checking and watch how your project will rise!

This is because TypeScript bases on comments like JSDoc where documentation of your JS-Codebase enhances, at least if using JSDoc. I can’t deny that you only get some meaningful features that TypeScript offers and would come with a full migration.

To draw a conclusion here: Anything is better than nothing. It behaves like pizza. If you eat it when it is cold, it is not as good as a hot one, but pizza is pizza 🍕.

Lessons and examples are booooring? Neither remember what you’ve coded in your last video course nor what you’ve learned? Be together with your favorite heroes and characters of your favorite Games, Movies, and TV Shows in my ArnoldCode Academy.

References

JSDoc — Reference & 6 years of Software Development