TypeScript Module Declaration Vs Augmentation

Just a quick writeup on a simple but perhaps not an entirely obvious feature of TypeScript.

TypeScript modules are written in one of two modes: declaration mode or augmentation mode. The difference is that in declaration mode, you can declare new top-level declarations - wow, that's a mouthful - but you can't update existing ones whereas in augmentation mode it's vice versa.

Real-life example is extending React to support onTouchTap attribute.

If you have a, say, on-touch-tap-react.d.ts declaration file that looks like this

declare module 'react' {  
    interface HTMLProps<T> {
        onTouchTap?: React.EventHandler<React.TouchEvent<T>>;
    }
}

You'll get a flurry of errors from tsc because, whoa, you've just overwritten react.

What you need to do instead is:

import React from 'react';

declare module 'react' {  
  interface HTMLProps<T> {
    onTouchTap?: React.EventHandler<React.TouchEvent<T>>;
  }
}

The only difference is the import statement at the top of the file which switches the module to the augmentation mode, hence updating reactrather than overwriting it.

Well, good to know.

Happy augmenting! I'm @tomas_brambora.