Ambient Variable Declarations

An ambient variable declaration is a way to tell TypeScript about a global variable that can be used in any .ts or .d.ts file in your project without explicitly importing it first.

Let’s say you’re running a NodeJS program in your browser, and the program checks process.env.NODE_ENV (which is either "development" or "production") at some point. When you run the program, you get an ugly runtime error:

Uncaught ReferenceError: process is not defined.

You sleuth around Stack Overflow a bit, and realize that the quickest hack to get your program running is to polyfill process.env.NODE_ENV yourself and hardcode it. So you create a new file, polyfills.ts, and define a global process.env:

process = {
  env: {
    NODE_ENV: 'production'
  }
}

Of course, TypeScript then comes to the rescue, throwing a red squiggly at you to try to save you from the mistake you’re clearly making by augmenting the window global:

Error TS2304: Cannot find name 'process'.

But in this case, TypeScript is being overprotective. You really do want to augment window, and you want to do it safely.

So what do you do? You pop open polyfills.ts in Vim (you see where this is going) and type:

declare let process: {
  env: {
    NODE_ENV: 'development' | 'production'
  }
}

process = {
  env: {
    NODE_ENV: 'production'
  }
}

You’re declaring to TypeScript that there’s a global object process that has a single property env, that has a property NODE_ENV. Once you tell TypeScript about that, the red squiggly disappears and you can safely define your process global.

Ambient Type Declarations

Ambient type declarations follow the same rules as ambient variable declarations: the declaration has to live in a script-mode .ts or .d.ts file, and it’ll be available globally to the other files in your project without an explicit import. For example, let’s declare a global utility type ToArray<T> that lifts T to an array, if it isn’t an array already. We can define this type in any script-mode file in our project—for this example, let’s define it in a top-level types.ts file:

type ToArray<T> = T extends unknown[] ? T : T[]

We can now use this type from any project file, without an explicit import:

function toArray<T>(a: T): ToArray<T> {
  // ...
}

Consider using ambient type declarations to model data types that are used throughout your application. For example, you might use them to make the UserID type we developed in “Simulating Nominal Types” globally available:

type UserID = string & {readonly brand: unique symbol}

Now, you can use UserID anywhere in your application without having to explicitly import it first.

Ambient Module Declarations

When you consume a JavaScript module and want to quickly declare some types for it so you can use it safely—without having to contribute the type declarations back to the JavaScript module’s GitHub repository or DefinitelyTyped first—ambient module declarations are the tool to use.

An ambient module declaration is a regular type declaration, surrounded by a special declare module syntax:

declare module 'module-name' {
  export type MyType = number
  export type MyDefaultType = {a: string}
  export let myExport: MyType
  let myDefaultExport: MyDefaultType
  export default myDefaultExport
}

A module name ('module-name' in this example) corresponds to an exact import path. When you import that path, your ambient module declaration tells TypeScript what’s available:

import ModuleName from 'module-name'
ModuleName.a  // string

If you have a nested module, make sure you include the whole import path in its declaration:

declare module '@most/core' {
  // Type declaration
}

If you just want to quickly tell TypeScript “I’m importing this module—I’ll type it later, just assume it’s an any for now,” keep the header but omit the actual declaration:

// Declare a module that can be imported, where each of its imports are any
declare module 'unsafe-module-name'

Now if you consume this module, it’s less safe:

import {x} from 'unsafe-module-name'
x  // any

Module declarations support wildcard imports, so you can give a type to any import path that matches the given pattern. Use a wildcard (*) to match an import path:¹

// Type JSON files imported with Webpack's json-loader
declare module 'json!*' {
  let value: object
  export default value
}

// Type CSS files imported with Webpack's style-loader
declare module '*.css' {
  let css: CSSRuleList
  export default css
}

Now, you can load JSON and CSS files:

import a from 'json!myFile'
a  // object

import b from './widget.css'
b  // CSSRuleList

Jump ahead to “JavaScript That Doesn’t Have Type Declarations on DefinitelyTyped” for an example of how to use ambient module declarations to declare types for untyped third-party JavaScript.

Step 1: Add TSC

When working on a codebase that combines TypeScript and JavaScript, start by letting TSC compile JavaScript files alongside your TypeScript. In your tsconfig.json:

{
  "compilerOptions": {
  "allowJs": true
}

With this one change, you can now use TSC to compile your JavaScript. Just add TSC to your build process, and either run every existing JavaScript file through TSC,³ or continue running legacy JavaScript files through your existing build process and run new TypeScript files through TSC.

With allowJs set to true, TypeScript won’t typecheck your existing JavaScript code, but it will transpile it (to ES3, ES5, or whatever target is set to in your tsconfig.json) using the module system you asked for (in your tsconfig.json’s module field). First step, done. Commit it, and give yourself a pat on the back—your codebase now uses TypeScript!

Step 2a: Enable Typechecking for JavaScript (Optional)

Now that TSC is processing your JavaScript, why not typecheck it too? While you might not have explicit type annotations in your JavaScript, remember how great TypeScript is at inferring types for you; it can infer types in your JavaScript the same way it does in your TypeScript code. Enable this in your tsconfig.json:

{
  "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}

Now, whenever TypeScript compiles a JavaScript file it’ll do its best to infer types and typecheck as it goes, like it does for regular TypeScript code.

If your codebase is big and flipping on checkJs reports too many type errors at once, turn it off, and instead enable checking for a JavaScript file at a time by adding the // @ts-check directive (a regular comment at the top of the file). Or, if a few big files are throwing the bulk of your errors and you don’t want to fix them just yet, keep checkJs on and add the // @ts-nocheck directive to just those files.

{
  "compilerOptions": {
  "allowJs": true,
  "checkJs": true,
  "noImplicitAny": false
}

When TypeScript runs over JavaScript code, it uses a more lenient inference algorithm than it does for TypeScript code. Specifically:

• All function parameters are optional.

• The types of properties on functions and classes are inferred from usage (rather than having to be declared up front):

 class A {
   x = 0 // number | string | string[], inferred from usage
   method() {
     this.x = 'foo'
   }
   otherMethod() {
     this.x = ['array', 'of', 'strings']
   }
 }

• After declaring an object, class, or function, you can assign extra properties to it. Under the hood, TypeScript does this by generating a corresponding namespace for each class and function declaration, and automatically adding an index signature to every object literal.

Step 2b: Add JSDoc Annotations (Optional)

Maybe you’re in a hurry, and just need to add a single type annotation for a new function you added to an old JavaScript file. Until you get a chance to convert that file to TypeScript, you can use a JSDoc annotation to type your new function.

You’ve probably seen JSDoc before; it’s those funny-looking comments above some JavaScript and TypeScript code with @-annotations like @param, @returns, and so on. TypeScript understands JSDoc, and uses it as input to its typechecker the same way that it uses explicit type annotations in TypeScript code.

Let’s say you have a 3,000-line utilities file (yes, I know your “friend” wrote it). You add a new utility function to it:

export function toPascalCase(word) {
  return word.replace(
    /w+/g,
    ([a, ...b]) => a.toUpperCase() + b.join('').toLowerCase()
  )
}

Without converting utils.js to TypeScript full sail—which would probably catch a bunch of bugs you’d then have to fix—you can annotate just your toPascalCase function, carving out a little island of safety in a sea of untyped JavaScript:

/**
 * @param word {string} An input string to convert
 * @returns {string} The string in PascalCase
 */
export function toPascalCase(word) {
  return word.replace(
    /w+/g,
    ([a, ...b]) => a.toUpperCase() + b.join('').toLowerCase()
  )
}

Without that JSDoc annotation, TypeScript would have inferred toPascalCase’s type as (word: any) => string. Now, when TypeScript compiles your code it knows toPascalCase’s type is (word: string) => string. And you got some nice documentation out of it!

Head over to the TypeScript Wiki to learn more about supported JSDoc annotations.

Step 3: Rename Your Files to .ts

Once you’ve added TSC to your build process, and optionally started typechecking and annotating JavaScript where possible, it’s time to start switching over to TypeScript.

One file at a time, update your files’ extensions from .js (or .coffee, .es6, etc.) to .ts. As soon as you rename a file in your code editor, you’ll see your friends the red squigglies appear (the TypeError, not the kids’ TV show), uncovering type errors, missed cases, forgotten null checks, and misspelled variable names. There are two strategies for fixing these errors:

1. Do it right. Take your time to type shapes, fields, and functions correctly, so you can catch errors in all the files that consume them. If you have checkJs enabled, turn on noImplicitAny in your tsconfig.json to uncover anys and type them, then turn it back off to make the output of typechecking your remaining JavaScript files less noisy.

2. Do it fast. Mass-rename your JavaScript files to the .ts extension, and keep your tsconfig.json settings lax (meaning strict set to false) to throw as few type errors as possible after renaming. Type complex types as any to appease the typechecker. Fix whatever type errors remain, and commit. Once this is done, flip on the strict mode flags (noImplicitAny, noImplicitThis, strictNullChecks, and so on) one by one, and fix the errors that pop up. (See Appendix F for a full list of these flags.)

// globals.ts
type TODO_FROM_JS_TO_TS_MIGRATION = any

// MyMigratedUtil.ts
export function mergeWidgets(
  widget1: TODO_FROM_JS_TO_TS_MIGRATION,
  widget2: TODO_FROM_JS_TO_TS_MIGRATION
): number {
  // ...
}

Both ways of doing it are fair game, and it’s up to you which you want to go with. Because TypeScript is a gradually typed language, it’s built from the ground up to interoperate with untyped JavaScript code as safely as possible. Regardless of whether you’re interoperating strictly typed TypeScript with untyped JavaScript or strictly typed TypeScript with loosely typed TypeScript, TypeScript will do its best to make sure that you’re doing it as safely as possible, and that on the strictly typed island that you’ve so carefully built, everything is as safe as it can be.

Step 4: Make It strict

Once you’ve migrated a critical mass of your JavaScript over to TypeScript, you’ll want to make your code as safe as possible by opting into TSC’s more stringent flags one by one (see Appendix F for a full list of flags).

Finally, you can disable TSC’s JavaScript interoperability flags, enforcing that all of your code is written in strictly typed TypeScript:

{
  "compilerOptions": {
  "allowJs": false,
  "checkJs": false
}

This will surface the final rounds of type-related errors. Fix these, and you’re left with a pristine, safe codebase that the most hardcore OCaml engineer would give you a pat on the back for (were you to ask nicely).

Following these steps will get you far when adding types to JavaScript you control, but what about JavaScript you don’t control, like code you installed from NPM? To get there, we’re first going to have to take a small detour…

JavaScript That Comes with Type Declarations

You know that a package comes with type declarations out of the box if you import it with {"noImplicitAny": true} and TypeScript doesn’t throw a red squiggly at you.

If the code you’re installing is compiled from TypeScript, or its authors were kind enough to include type declarations in its NPM package, then you’re in luck. Just install the code and start using it with full type support.

Some examples of NPM packages that come with built-in type declarations are:

npm install rxjs
npm install ava
npm install @angular/cli

JavaScript That Has Type Declarations on DefinitelyTyped

Even if the third-party code you’re importing doesn’t come with type declarations, declarations for it are probably available on DefinitelyTyped, TypeScript’s community-maintained, centralized repository for ambient module declarations for open source projects.

To check if the package you installed has type declarations available on DefinitelyTyped, either search on TypeSearch or just try installing the declarations. All DefinitelyTyped type declarations are published to NPM under the @types scope, so you can just npm install from that scope:

npm install lodash --save            # Install Lodash
npm install @types/lodash --save-dev # Install type declarations for Lodash

Most of the time, you’ll want to use npm install’s --save-dev flag to add your installed type declarations to your package.json’s devDependencies field.

JavaScript That Doesn’t Have Type Declarations on DefinitelyTyped

This is the least common case of the three. You have several options here, from the cheapest and least safe to the most time-intensive and safest:

1. Whitelist the specific import by adding a // @ts-ignore directive above your untyped import. TypeScript will let you use the untyped module, but the module and all of its contents will be typed as any:

   // @ts-ignore
   import Unsafe from 'untyped-module'
   
   Unsafe  // any

2. Whitelist all usages of this module by creating an empty type declaration file and stubbing out the module. For example, if you installed the rarely used package nearby-ferret-alerter, you could make a new type declaration (e.g., types.d.ts) and add to it the ambient type declaration:

   // types.d.ts
   declare module 'nearby-ferret-alerter'

   This tells TypeScript that there exists a module that you can import (import alert from 'nearby-ferret-alerter'), but it doesn’t tell TypeScript anything about the types contained in that module. This approach is a slightly better alternative to the first, in that now there’s a central types.d.ts file that enumerates all the untyped modules in your application, but it’s equally unsafe because nearby-ferret-alerter and all of its exports will still be typed as any.

3. Create an ambient module declaration. Like in the previous approach, create a file called types.d.ts and add an empty declaration (declare module 'nearby-ferret-alerter'). Now, fill in the type declaration. For example, the result might look like this:

   // types.d.ts
   declare module 'nearby-ferret-alerter' {
     export default function alert(loudness: 'soft' | 'loud'): Promise<void>
     export function getFerretCount(): Promise<number>
   }

   Now when you import alert from 'nearby-ferret-alerter', TypeScript will know exactly what alert’s type is. It’s no longer an any, but (loudness: 'quiet' | 'loud') => Promise<void>.

4. Create a type declaration and contribute it back to NPM. If you got as far as the third option and now have a local type declaration for your module, consider contributing it back to NPM so the next person that needs type declarations for the awesome nearby-ferret-alerter package can use it too. To do this you can either submit a pull request to the nearby-ferret-alerter Git repository and contribute the type declarations directly, or, if the maintainers of that repository don’t want to be on the hook for maintaining TypeScript type declarations, contribute your declarations to DefinitelyTyped instead.

Writing type declarations for third-party JavaScript is straightforward, but how it’s done depends on the type of module you’re typing. There are a few common patterns that come up when typing different kinds of JavaScript modules (from NodeJS modules to jQuery augmentations and Lodash mixins to React and Angular components). Head over to Appendix D for a list of recipes for typing third-party JavaScript modules.