Globals & module augmentation

A global TypeScript has never heard of

A shop page loads an analytics script with a <script> tag. The script makes a global: a name that every script on the page can use, here analytics. Your code calls it when a shopper adds tea to the cart:

analytics.track("add_to_cart");
console.log("Tea added to the cart");

Line 1 calls analytics.track, which the analytics script wrote. It prints Tracked add_to_cart. Line 2 prints Tea added to the cart. In this lesson, a setup file stands in for the page's scripts, so every example runs the way the lesson says when you press Edit & run.

Now the same two lines in a TypeScript file:

1analytics.track("add_to_cart");2console.log("Tea added to the cart");

TypeScript marks line 1 with Cannot find name 'analytics', on purpose here. It means "nothing in your code says what analytics is". TypeScript reads your files. It never sees the page's <script> tags, so a name that a script makes while the page runs is new to it. The code still runs and prints both lines, because the page does have analytics.

The fix is one line that describes the global. declare means "this exists already; here is its type":

1declare const analytics: {2  track(event: string): void;3};4 5analytics.track("add_to_cart");6console.log("Tea added to the cart");

Lines 1 to 3 tell TypeScript that a constant called analytics exists, with a track method that takes a string. They don't create anything. Line 5 now checks, and line 6 prints as before. There are no errors.

declare: describe a name, don't create it

You can declare any kind of name this way. A page often has a constant from the build tool and a function from a script:

1declare const __APP_VERSION__: string;2declare function gtag(command: "event", name: string): void;3 4console.log(`Version ${__APP_VERSION__}`);5gtag("event", "add_to_cart");

• Line 1 declares __APP_VERSION__, a string. Vite's define option writes the real version into your code when it builds, and Vite's guide tells you to declare it exactly like this.
• Line 2 declares gtag, the function Google's analytics script makes. A declared function has no body: only its parameters and what it gives back. void means it gives back nothing useful.
• Line 4 prints Version 1.4.0, and line 5 prints gtag: event add_to_cart, from the stand-ins for the page.

A declare line is all type, so it's removed with the other types. This is what's left for the browser:

console.log(`Version ${__APP_VERSION__}`);
gtag("event", "add_to_cart");

Lines 1 and 2 are the two lines that did something. Both declare lines are gone. TypeScript calls declared names ambient: they are described here and made somewhere else. That's why a declare line can't hold a value:

1declare const shopName: string = "Tea House";

Initializers are not allowed in ambient contexts means "a described name can't be given a value here". An initializer is the = "Tea House" part. If you want to make the constant, drop declare.

What you write after the colon decides how much TypeScript checks. Press each button and watch the list under the code. Line 4 has a typo on purpose: trak instead of track.

1// analytics isn't declared2 3analytics.track("add_to_cart");4analytics.trak("checkout");

Only declare its shape catches the typo. With declare as any, TypeScript accepts everything, and line 4 throws a TypeError when it runs (the any, unknown & never lesson covers both types). The code runs the same way with every button, because line 1 is removed before it runs. A declaration changes what TypeScript says, never what the page does.

Globals from a module: declare global

Where you put a declaration matters. A file with an import or export is a module, and the names it declares belong to that file only (Modules & type imports covers this, and Why modules the JavaScript side). A file with neither is a script, and its top-level names are global: every file sees them. Most files in a project are modules, and so is every example on this page.

So declare const analytics in a module describes analytics for that one file. To describe it for every file, put it inside a declare global block:

1type Analytics = { track(event: string): void };2 3declare global {4  const analytics: Analytics;5}6 7analytics.track("add_to_cart");

Line 1 gives the analytics object's shape a name, Analytics, with a type alias. Lines 3 to 5 are the declare global block. Everything inside it is added to the global scope, the names every file shares. You don't write declare again inside it. Line 7 calls track and prints Tracked add_to_cart.

There are two places for global declarations, and you'll see both in real projects:

• A script file with no import or export, often named globals.d.ts. A .d.ts file holds only types. Its declarations are global already, so you write declare const analytics: Analytics; without a wrapper.
• A declare global block in a module. You need this as soon as the file imports a type. One import line turns a script into a module, and then its plain declare const stops being global: other files get Cannot find name again.

A declare global block only works in a module. In a script file, TypeScript reports Augmentations for the global scope can only be directly nested in external modules or ambient module declarations: there, everything is global already. An augmentation is an addition to something that already exists.

Inside declare global, const and var aren't the same. Say the server writes the cart count into the page, and you read it as window.cartCount:

1declare global {2  const cartCount: number;3}4 5console.log(cartCount);6console.log(window.cartCount);

Line 5 is fine: cartCount is a global name. Line 6 gets Property 'cartCount' does not exist on type 'Window & typeof globalThis'. That long type is what TypeScript gives window: everything the Window interface lists, joined with every global name declared with var or function. In JavaScript, a global var also becomes a property of window, but a global const or let doesn't (var and the global object shows why). TypeScript follows the same rule. The code still prints 3 twice, because the page set window.cartCount. Declare it with var instead:

1declare global {2  var cartCount: number;3}4 5console.log(cartCount);6console.log(window.cartCount);7//                 ^?

The only change is var on line 2. Line 6 now checks, and the query on line 7 shows that window.cartCount is the same global: var cartCount: number. Both lines print 3.

The table below sums it up. Read each row as: this declaration inside declare global, then the two ways to use it.

Adding to Window for a script that may not load

The Declaration merging lesson added a property to Window by declaring the interface again inside declare global. Your Window joins the browser's. Here is the question that lesson left open: what if the script that sets the property never runs?

Say the shop loads a help-chat script that sets window.chat. Ad blockers stop scripts like this, and a slow network can delay them. So the honest type is optional, written with a ?: the property may be missing.

1type Chat = { open(): void };2 3declare global {4  interface Window {5    chat?: Chat;6  }7}8 9window.chat.open();10console.log("Help requested");

Line 1 names the chat's shape. Lines 3 to 7 add an optional chat to Window. Line 9 calls open without checking, and TypeScript says 'window.chat' is possibly 'undefined': the chat may not be there. On this page there is no chat script, so line 9 throws a TypeError and line 10 never runs.

1type Chat = { open(): void };2 3declare global {4  interface Window {5    chat?: Chat;6  }7}8 9window.chat?.open();10console.log("Help requested");

Line 9 now uses ?., which calls open only when window.chat isn't undefined (Nullish and optional chaining covers it). The error is gone, and line 10 prints Help requested with or without the chat.

Notice that the code reads window.chat, not a bare chat. Reading a property that isn't there gives undefined. Reading a global name that doesn't exist throws, and ?. can't help:

chat?.open();
console.log("Help requested");

Line 1 throws ReferenceError: chat is not defined before ?. gets a chance. So for anything a script might not create, add an optional property to Window and read it through window.

Adding to a package's types

Packages you install from npm come with their own types, in .d.ts files. Say the shop uses a small UI package called shop-ui. Its types describe a theme with a font size, and a createTheme function:

1export interface Theme {2  fontSize: number;3}4 5export declare function createTheme(theme: Theme): Theme;

Lines 1 to 3 describe Theme as an interface with a fontSize. Line 5 declares createTheme, which takes a Theme and gives one back. The shop wants a brand color in its theme too. You can't edit files in node_modules: the next install overwrites them. Instead, you add to the package's types from your own code with a declare module block. This is called module augmentation.

This playground checks a small project for real: your src/app.ts and the installed shop-ui. Press each button and watch the list under the code.

1import { createTheme } from "shop-ui";2 3const theme = createTheme({ fontSize: 16, brandColor: "orange" });4console.log(theme.brandColor);

With Nothing added, brandColor isn't part of Theme, so line 3 and line 4 are marked. With declare module "shop-ui", lines 3 to 7 add brandColor to shop-ui's Theme and every error is gone. The other two buttons show the two rules that break it most often.

Module augmentation has three rules:

1. The name in quotes is the name you import the package by: "shop-ui". A misspelled name gets Invalid module name in augmentation.
2. You add to an interface, the same way two interfaces merge. A type can't be added to; it gets Duplicate identifier 'Theme'.
3. The file must be a module. In a project you usually move the block into its own file, like src/shop-ui.d.ts, with import "shop-ui"; as its first line. Without an import or export, the file is a script, and there declare module "shop-ui" means something else: it describes the whole package, and TypeScript uses it instead of shop-ui's own types. Then importing createTheme fails with Module '"shop-ui"' has no exported member 'createTheme'.

Real packages expect this. Emotion, a styling package, gives its Theme interface no properties, and its guide tells you to fill it in with declare module '@emotion/react' in a file that starts with import '@emotion/react'.

Typing environment variables

An environment variable is a setting that comes from outside your code, like the address of the shop's API, which differs between your laptop and the live site. Vite reads them from a file named .env and gives the ones whose names start with VITE_ to your code as import.meta.env.VITE_API_URL.

Vite's own types describe import.meta.env with an interface called ImportMetaEnv. You add your variables to it. This page doesn't have Vite's types, so lines 2 to 5 stand in for them:

1declare global {2  // Vite's own types declare this part (shortened)3  interface ImportMeta {4    readonly env: ImportMetaEnv;5  }6  // You add your own variables here7  interface ImportMetaEnv {8    readonly VITE_API_URL: string;9  }10}11 12const apiUrl = import.meta.env.VITE_API_URL;13//    ^?14const shopUrl = import.meta.env.VITE_SHOP_URL;

Lines 3 to 5 say that import.meta has an env of type ImportMetaEnv. Lines 7 to 9 add VITE_API_URL, a string. readonly means your code can read it but not change it. The query on line 13 shows const apiUrl: string. Line 14 gets an error on purpose: Property 'VITE_SHOP_URL' does not exist on type 'ImportMetaEnv'. Did you mean 'VITE_API_URL'?

In a Vite project you write only lines 7 to 9, without declare global, in src/vite-env.d.ts. That file must stay a script: Vite's guide warns that an import in it breaks the addition, because the interface would then belong to that file only. One more difference: Vite's real ImportMetaEnv lets any other name through as any, so a misspelled variable isn't marked unless you turn on its strictImportMetaEnv option.

Next.js and Node read variables from process.env instead. Node's types (@types/node) describe it with an interface called ProcessEnv inside a namespace called NodeJS, where every name is string | undefined. You add your own names to that interface the same way, inside declare global. Exercise 6 has you do it.

These types are promises you make to TypeScript. It doesn't open .env. If the variable isn't set, Vite writes undefined into the code where you used it, and TypeScript still says string.

One types file for a shop's globals

Real projects keep these declarations in one place, so everyone knows where to look. Here is a types file for the shop: the version from the build, the analytics script, and the optional chat.

1export {};2 3type Analytics = { track(event: string): void };4type Chat = { open(): void };5 6declare global {7  const __APP_VERSION__: string;8  var analytics: Analytics;9 10  interface Window {11    chat?: Chat;12  }13}14 15analytics.track(`checkout_v${__APP_VERSION__}`);16window.chat?.open();

• Line 1, export {};, exports nothing. It's there to make the file a module, so that the declare global block on line 6 is allowed. In your project, this file could be src/globals.d.ts.
• Lines 3 and 4 name the shapes of the two scripts' objects. They stay in this file.
• Line 7 declares the build's version. Line 8 uses var, so analytics also works as window.analytics. Lines 10 to 12 add the optional chat to Window.
• Lines 15 and 16 stand in for the rest of your code, which in a project lives in other files. This page checks one file at a time, so they share it here. Line 15 prints Tracked checkout_v1.4.0. Line 16 does nothing, because this page has no chat.

The table below is a short guide. Read each row as: what you want to add, what to write, and where it goes.

Common mix-ups

• "declare creates the variable." No. It only describes a name, and it's removed before the code runs. If the script never loads, the code still fails.
• "TypeScript checks that the real global matches my declaration." No. It can't see the page while it runs. It trusts what you wrote, the same way it trusts a type on JSON.parse.
• "Inside declare global, const and var are the same." No. Only a var is also a property of window. With const, window.cartCount is an error.
• "?. protects a bare global name." No. A name that doesn't exist throws a ReferenceError before ?. runs. Read it as window.chat?.open().
• "declare module "shop-ui" always adds to the package." No. Only in a module. In a file with no import or export, it replaces the package's types.
• "I can add to a package's type alias." No. Only interfaces merge. A second type with the same name is a Duplicate identifier error.
• "Typing VITE_API_URL makes sure it's set." No. TypeScript never reads .env. A missing variable is undefined when the page runs.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and the console shows what it prints. The page's stand-ins for analytics, gtag, __APP_VERSION__, and process are there too. Try a guess first, then use the hints.

declare const analytics: { track(event: string): void };

analytics.track("add_to_cart");
gtag("event", "checkout");

1declare const analytics: { track(event: string): void };2declare function gtag(command: "event", name: string): void;3 4analytics.track("add_to_cart");5gtag("event", "checkout");

1declare const __APP_VERSION__: string;2declare function gtag(command: "event", name: string): void;3 4gtag("event", `version_${__APP_VERSION__}`);

1declare const __APP_VERSION__: string;2declare function gtag(command: "event", name: string): void;3 4// The browser gets only the next line:5gtag("event", `version_${__APP_VERSION__}`);

1declare global {2  const shopName: string;3}4 5window.shopName = "Tea House";6console.log(shopName);

1declare global {2  var shopName: string;3}4 5window.shopName = "Tea House";6console.log(shopName);

1type Chat = { open(): void };2 3declare global {4  interface Window {5    chat?: Chat;6  }7}8 9window.chat.open();10console.log("Help requested");

1type Chat = { open(): void };2 3declare global {4  interface Window {5    chat?: Chat;6  }7}8 9window.chat?.open();10console.log("Help requested");

1// Write the declaration for gtag here2 3gtag("event", "add_to_cart");4gtag("event", "checkout");5gtag("event", "chekout");

1declare function gtag(command: "event", name: "add_to_cart" | "checkout"): void;2 3gtag("event", "add_to_cart");4gtag("event", "checkout");5gtag("event", "chekout");

1// Stands in for what @types/node declares (shortened)2declare global {3  namespace NodeJS {4    interface ProcessEnv {5      [name: string]: string | undefined;6    }7  }8  var process: { env: NodeJS.ProcessEnv };9}10 11const apiUrl: string = process.env.NEXT_PUBLIC_API_URL;12console.log(apiUrl);

1// Stands in for what @types/node declares (shortened)2declare global {3  namespace NodeJS {4    interface ProcessEnv {5      [name: string]: string | undefined;6    }7  }8  var process: { env: NodeJS.ProcessEnv };9}10 11// Your addition12declare global {13  namespace NodeJS {14    interface ProcessEnv {15      NEXT_PUBLIC_API_URL: string;16    }17  }18}19 20const apiUrl: string = process.env.NEXT_PUBLIC_API_URL;21console.log(apiUrl);

Check your understanding

For each question, keep two things apart: what TypeScript knows from your declarations, and what really exists on the page when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript only knows names your code declares. A global from a script tag or a build tool needs a declare line.
• declare describes; it never creates. It's removed before the code runs, and it can't hold a value.
• In a module, use declare global { … } to add names every file sees. Only a var there is also on window.
• For a script that may not load, add an optional property to Window and call it with window.chat?.open().
• declare module "shop-ui" in a module adds to a package's interfaces. In a script file, it replaces them.
• Add your environment variables to ImportMetaEnv or NodeJS.ProcessEnv. TypeScript still never checks .env.

Coming next: Strict mode options. It turns on TypeScript's checks one flag at a time, and shows which extra checks are worth adding.