Summary:

declare is a command used to inform the compiler that a certain element, usually a variable, already exists and can be referenced by other code without needing to be compiled into JavaScript.

Typical Scenario:

Imagine you include a JavaScript file in your webpage from an external source like 'foo.com'. This script creates an object with useful methods and assigns it to the identifier 'fooSdk' globally. Your TypeScript code needs to call fooSdk.doSomething(), but since the compiler is unaware of the existence of the 'fooSdk' variable, it will throw a compilation error.

To resolve this issue, you use the declare keyword to reassure the compiler that the variable 'fooSdk' does exist with a specific type. While this statement helps the compiler perform static checks on the code, it does not generate any JavaScript output for the declaration.

declare const fooSdk = { doSomething: () => boolean }

Newer versions of TypeScript require a slightly modified syntax:

declare const fooSdk : { doSomething: () => boolean }

You can also apply the declare keyword to class properties to prevent the compiler from emitting any code related to creating those properties. This is useful when your own code handles the property creation, which may not be fully understood by the compiler.

It's worth noting that when declaring types, as opposed to variables, there is no impact on the resulting JavaScript output. Whether there is a practical reason to declare a type remains uncertain.

Consider this practical scenario.

In my TypeScript React application, I utilize the Webpack Hot Middleware. Despite being written in plain JavaScript, the Webpack Hot Middleware lacks type declarations for the TypeScript compiler to verify against.

Upon execution of my code, the module object provided by the Webpack Hot Middleware is accessible for logging, even though it is pure JavaScript coexisting within my sophisticated TypeScript React environment.

The module object contains keys like module.hot, each potentially holding values. However, the TypeScript design-time compiler (especially in VSCode) flags these keys with red squiggly lines, stating that property 'hot' does not exist. Contrary to this warning, the property indeed exists!

To appease the TypeScript compiler, a simple declaration can be added:

declare let module: any

By assigning the existing module object a type of any, the TypeScript compiler no longer displays errors, allowing me to seamlessly compile and develop additional code.

If you omit the keyword declare and only specify let module: any, you will encounter compilation issues reporting that 'module' already exists. This is where the term "ambient" as discussed in the solution comes into play.

According to the Typescript documentation:

Typescript - Working with Other JavaScript Libraries

If we want to describe the structure of libraries that are not in TypeScript, we must declare the API that the library provides. Since many JavaScript libraries only expose a few main objects, namespaces are a useful way to represent them.

Ambient declarations refer to those that do not include an implementation. These types are often found in .d.ts files. For those familiar with C/C++, these can be likened to .h files. Let's explore some examples.

Defining Ambient Namespaces

The well-known D3 library defines its features within a global object called d3. As this library is typically loaded through a script tag (instead of a module loader), namespaces are used for defining its structure. To ensure that the TypeScript compiler recognizes this structure, we utilize an ambient namespace declaration. An example snippet may look like this:

D3.d.ts (simplified extract)

declare namespace D3 {
    export interface Selectors {
        select: {
            (selector: string): Selection;
            (element: EventTarget): Selection;
        };
    }
    // (...)
}

Prior to coding the actual implementation, it is possible to utilize the declare keyword in order to inform the compiler about the types, ensuring TypeScript's contentment.

declare function bar(surname: string): string

Imagine this situation: You are working on a Typescript project, but then you find yourself needing to create a module in JavaScript for some specific reason and integrate it into your Typescript code.

// getName.js
module.exports = function getName(name) {
    return name;
}

Next, you bring this JS module into your Typescript code.

// myCode.ts
import getName from 'getName'; //getName is a JS module and not written in TypeScript

However, when importing this JS module (make sure the allowJs compiler option is set to false, or else JS files will be resolved without proper type definitions), the Typescript compiler gives an error stating that the module is not recognized as a valid module!

No declaration file found for module '/absolute/path/to/getName.ts'

This issue arises because Typescript does not automatically understand JS code. To fix this problem, we need to provide a type definition (filename.d.ts) for our JS module using the declare and export keywords.

// getName.d.ts
declare function getName(name: string): string;

export default getName;

Once this type definition is added, Typescript no longer complains about the JS module since it now has access to the necessary types.