How to add custom "typings" in typescript 2.0 / 3.0

Question

According to this article typings system for typescript 2.0 has changed and so it is not clear how to attach custom typings now. Should I always create NPM package for that?

Thank you in advance!

Colza

Do you mean module augmentation (i.e extending modules)? – Toucan

Just a simple thing, need to provide declarations for external JS code not covered with "@type" system (there is no way that I can publish those types through npm, the code and the interfaces are private) – Colza

Answer 1

You can create local custom typings just for your project, where you can declare types for JS libraries. For that, you need to:

1. Create directory structure to keep your type declaration files so that your directory structure looks similar to this:

    .
    ├── custom_typings
    │   └── some-js-lib
    │       └── index.d.ts
    └── tsconfig.json
   

2. In the index.d.ts file, add a declaration for your JS library:

    declare module 'some-js-lib' {
      export function hello(world: string): void
    }
   

3. (Optional: skip if you have TypeScript >= 4.x) Add a reference to this type declaration in the compilerOptions section of your tsconfig.json:

    {
      "compilerOptions": {
        ...
        "typeRoots": ["./node_modules/@types", "./custom_typings"]
      },
      ...
    }
   

4. Use the declared module in your code:

    import { hello } from 'some-js-lib'
   
    hello('world!')
   

Cleghorn

I'm not sure step 3 is necessary. It seems to work for me without it. Also it seems like that index.d.ts or declarations.d.ts can go anywhere in the project. – Hospitaler

Yes, you can put your declare module ... into any .d.ts file. – Cleghorn

Step 3 is necessary, but you only need to specify "typeRoots", not "types". Also, you will wipe out the default path, so you should use "typeRoots": ["custom_typings", "node_modules/@types"] – Warrant

@StevenSpungin, it seems that you don't need to specify node_modules/@types – at least not with TS 2.1. – Cleghorn

Once you override typeRoots, it ignores node_modules/@types. So "typeRoots": ["custom_typings"] disables the default behavior. You need to add it back in. This is clearly document in typescriptlang.org/docs/handbook/… – Warrant

What is the difference above, if you want to use this custom typing in another project? – Polyhedron

@StevenSpungin I've checked it with TypeScript 2.5.3 and you are correct – it is no longer needed to explicitly reference typed modules, and yes, you also now need to add node_modules/@types back. I've updated the answer, thanks! – Cleghorn

What if you want your custom types to appear among declarations generated by tsc? – Batten

I have declared typings in same way but I am geeting error - Cannot find module 'testFunction'. while using import { hello } from "testFunction"; . Is It require to register custom typings any where in angular ? – Network

@doublejosh Did you found a solution? – Priestridden

@FernandoMontoya The solution I found is to specify ".ts" when I import my worker. I have no clue why import Worker from './worker.ts' – Toxicology

Not sure about Angular, I just tried this in a blank project and it seems to be working, at least with default tsconfig.json. In fact, specifying typeRoots in step 3 doesn't seem to be necessary anymore 🤔 – Cleghorn

Just tried the same and got it working without step 3 ("typeRoots"). – Sovereignty

@Network i have the same issue, have you managed to find a solution? – Excruciation