Table of Contents Preface typescript angular

Declaration Files

It would be a shame if we could not use the myr­iad of ex­ist­ing JavaScript li­braries, frame­works and npm mod­ules in con­junc­tion with our Type­Script code. In or­der to seam­lessly in­te­grate ex­ter­nal li­braries with your Type­Script pro­ject you have to make use of declaration files.

De­c­la­ra­tion files are marked with a .d.ts ex­ten­sion and de­scribe the in­ter­face of an JavaScript libarby. This al­lows the com­piler to pro­vide you with the same fea­tures, like in­tel­lisense or com­pile time er­ror mes­sages, as if the third-party code was writ­ten in Type­Script.

Ac­tu­ally, every in­stal­la­tion of Type­Script ships with a file called lib.d.ts. The files con­tains the Ec­maScript APIs, like window, Object or Math. This is an prime ex­am­ple how de­c­la­ra­tion files can fill in the gaps for JavaScript code Type­Script does not know about.

Definitely Typed

De­f­i­n­i­tion files are nice and all, but on the other hand there are re­quired when­ever you want to work with a third-party li­brary. For­tu­nately, soon af­ter Type­Script was re­leased Boris Yankov started the DefinitelyTyped pro­ject to host de­c­la­ra­tion files for pop­u­lar JavaScript li­braries. There are al­ready more than 2,000 de­f­i­n­i­tions for ex­ter­nal libaries, so if in doubt head over to definitelytyped.org!

For conce­nience there is also a tsd pack­age, which can be in­stalled via npm. The pack­age makes it pos­si­ble to in­stall de­c­la­ra­tion files from the DefinitelyTyped re­spos­i­tory di­rectly from the con­sole.[1] Af­ter the in­stal­la­tion you can use query to search and install to in­stall a de­c­la­ra­tion file to your pro­ject. De­c­la­ra­tion files will be in­stalled in a typings di­rec­tory by de­fault. You can point your IDE of choice to this di­rec­tory and Type­Scrip­t’s com­piler will do its magic.

Writing .d.ts Files

Even though there are tons of de­c­la­ra­tion files if you want to use a rather un­kown li­brary or if you are the au­thor of li­brary there is a chance that no .d.ts. file ex­ists for that li­brary. In this case you have to write you own de­c­la­ra­tion file. For more in­for­ma­tions on how to write de­c­la­ra­tion files visit the TypeScript Handbook.

An­other rea­son to write your own .d.ts files is when you want to work with global vari­ables. For in­stance the main HTML file of your SPA[2] may con­tain in­for­ma­tion about API end­points, which are in­serted by the server:

<body>
    ...
    <script type="text/javascript">
        var MARVEL_API_URL = {
            root: "https://gateway.marvel.com/",
            characters: "/v1/public/characters/:id",
            comics: "/v1/public/comics/:id"
        };
    </script>
</body>

The Type­Script com­piler does not know about the MARVEL_API_URL vari­able, be­cause this piece of code is out­side the Type­Scrip­t’s scope. Thus, try­ing to ac­cess the vari­able with the fol­low­ing ex­am­ple will re­sult in an er­ror.[3]

class MarvelApiService {
    static fetchComics () {
        return fetch( MARVEL_API_URL.comics, {
            method: 'get'
        });
    }
}

To solve the prob­lem we need to cre­ate a cus­tom de­c­la­ra­tion file and save it some­where the Type­Script com­piler can find it. The con­tent of our cus­tom de­c­la­ra­tion file should be this:

declare var MARVEL_API_URL: {
    root: string,
    characters: string,
    comics: string
}

Note that the Type­Script com­piler will scan your source di­rec­to­ries for .d.ts files and au­to­mat­i­cally in­clude them.

  1. tsd package on Github ↩

  2. Sin­gle Page Ap­pli­ca­tion ↩

  3. As­sum­ing the de­c­la­ra­tion file for fetch is pro­vided. ↩