Everything About TypeScript Declarations

It turns out that Typescript declaration files seem to be one of the complex things to grasp because of the lack of the documentation and vague explanations from community. In this article, We will all be 5 years old boys who will try to understand all of this in the most simplest way possible.

Finally, It’s happened. Cheers ! Olalalalala. You decided to move to Typescript because you think it’s really good or some morons told you that it’s good. In either case, You’re here.

When we write apps in Typescript, there’re cases when we don’t always have .ts files/modules. This means that we might sometimes have to write javascript files and use it in our ts files or use 3rd-party library at all which is written in javascript.

All these module resolution things will be shown for CommonJS module which works as node.js because Typescript has only 2 — classic or nodejs module resolution thing.

Local Javascript Files And Their Declarations

We decided to write our own javascript file(just a one-file module, not a library or something). That’s awesome, but we need to be cursed/doomed or whatever the highest level of hell is called, because writing js files when we use Typescript is an abominable sin. (Why?) If you can’t answer this, you wouldn’t need to read this article in the first place at all. So let’s continue.

I’m gonna create a hello.js file. (CommonJS).

Now, Let’s create app.ts file

Now, As we said, there’ll be a red line above ./hello which states that Typescript can’t find the declaration file for hello . How and where does Typescript search for the declaration file that it decided to tell us: “I can’t find it”. The answer depends on what module resolution we use. NodeJs or Classic. Let’s say it’s Node.js . So it’s gonna start searching for that file in this sequence .

Okay, so we could create hello.d.ts in the same directory as hello.js or create a folder and put the hello.d.ts or index.d.ts or any other names I logged above. Whatever you decide, it’s up to you. Here is the contents of that declaration file.

Now, Typescript found this. The idea is that even though this is what’s get included in Typescript file/World, when we build the project and we got actual javascript file, that js built file will still have require(./hello.js) and it’s still going to resolve to the actual code. Declarations are just for the development while we write the code so that Typescript could be our savior/guardian angel or whatever you wanna call it. I call it : TROUBLE.

3-rd Party Libraries And Their Declaration Files

This is another aspect. and we will go through the stages together. This case will be activated when we require 3rd-party library in our Typescript and that library is javascript. let’s say this library doesn’t have type declarations at all. I am going to use lodash library for its simplicity. So we have an app.ts file

This line will make the intellisence scream. Why? Let’s see the logs how Typescript tries to find the declaration file for lodash . Typescript will try to load ts module if it exists. if it doesn’t, it will try to load declaration file. it doesn’t, it will try to resolve to the actual js file which gives us the error that we are pretty well aware of.

So, It couldn’t find any declaration or any ts extension module in lodash library. So it gave us back the js extension. Hence the error. To solve this, we have 2 OPTIONS.

A) npm install @types/lodash This would solve our error, because as you can see, at some stage in the above logs, that’s where Typescript would try to find the declaration or module file.

B) This is a really advanced/tricky part. Let’s go on.
We have to make a declaration file. That’s for sure. Key point is it doesn’t matter where we create this file in our directory or in nested folders. Just create it. let’s call it brysh-lodash.d.ts. You can also create ts extension instead of d.ts , but then that would also get compiled as an empty file(since interface and this stuff produces no code when compiling). Ok, We created brysh-lodash.d.ts , who knows where. Now, the tricky part is, this is the code we are going to put it inside that file.

And we have this code in app.ts

Update: Also note that, sometimes 3rd-party libraries package.json contains the key types or typings and that’s where it specifies the types/declaration path.

typeRoots

Let’s talk about the most complex, damned, cursed ( i don’t know what else to call it since all the stackoverflow questions are all about it and there’s still nothing that really makes you understand it. I won’t even mention official docs. I have never seen something that stupid).

This will be my idea and logic and don’t depend on this information(who knows it might be wrong or right).

So, remember that we created brysh-lodash.d.ts file wherever we wanted and it would still get compiled which would let us use lodash ? Now, I have seen people do these kind of configs in their tsconfig.json

I am gathering all the info I might need to remember how typeRoots works.

Related posts:

For the office and pretty much only the office. Fairly straight-laced, it’s sometimes hard to innovate within this dress code, but we swear it is possible.

Originally published on my blog at Shiphp.com where you can find dozens of PHP and Docker tutorials and a link to my free Docker eBook. SQLite is a great database for getting started on small…