Declaration merging

Two interfaces, one type

An interface gives a name to an object type: interface User { name: string; } says every User has a name that is text. In JavaScript, declaring the same name twice is usually a mistake. For interfaces, TypeScript allows it on purpose, and the two declarations join. You saw this briefly in Type aliases & interfaces; this lesson shows how it works and where it's useful:

1interface User {2  name: string;3}4interface User {5  email: string;6}7 8const asha: User = { name: "Asha", email: "asha@example.com" };9console.log(asha.email);10//               ^?

Lines 1 to 3 declare User with a name. Lines 4 to 6 declare User again, with an email. There is no error: TypeScript joins the two into one User that has both. Line 8 makes asha, a User with a name and an email, and line 9 prints asha@example.com. The query on line 10 asks what email is, and TypeScript answers (property) User.email: string: the email from the second declaration belongs to the one User.

Because there is only one User, an object needs every property from both declarations:

1interface User {2  name: string;3}4interface User {5  email: string;6}7 8const sam: User = { name: "Sam" };

Line 8 makes sam with only a name. TypeScript marks line 8, on purpose here: Property 'email' is missing in type '{ name: string; }' but required in type 'User'. In plain words: the object you wrote has a name and nothing else, but a User must also have an email. Press Edit & run and add email: "sam@example.com" to line 8 to watch the error go away.

Joining declarations with the same name is called declaration merging. It sounds like a curiosity, but it's how you add your own properties to types you didn't write, like the browser's window.

How two interfaces join

Merging follows three rules:

• Every property from every declaration goes into the one type. Three or more declarations work too.
• A property can appear in more than one declaration, but only with the same type each time.
• The declarations must be in the same place: in one file, or all in the global scope that every file shares. The next section shows the global scope.

Try the first two rules on a settings object. Lines 1 to 3 declare Settings with a theme. Each button puts something different in the second declaration, on line 5. Line 8 makes an object with a theme and a font size.

1interface Settings {2  theme: string;3}4interface Settings {5  fontSize: number;6}7 8const settings: Settings = { theme: "dark", fontSize: 16 };9console.log(settings.theme, settings.fontSize);

Press each button and watch the list under the code. Add fontSize has no errors: the merged Settings has both properties. fontSize as text moves the error to line 8, because the object gives fontSize a number. Repeat theme names theme again with the same type, which is allowed. theme as a number gets Subsequent property declarations must have the same type on line 5: the later declaration disagrees with line 2. The console line never changes, because types are removed before the code runs. You can also press Edit & run and type your own line 5.

Adding your own property to Window

In the browser, window is the global object: it holds the page's global names (the var and the global object lesson covers it). Apps often put their own things on it, like feature flags the server sends with the page. In plain JavaScript you just set a new property. In TypeScript:

1window.featureFlags = { newCheckout: true };2console.log(window.featureFlags.newCheckout);

Line 1 sets window.featureFlags and line 2 reads it. TypeScript marks both lines, on purpose here: Property 'featureFlags' does not exist on type 'Window & typeof globalThis'. TypeScript comes with the browser's types, in a file called lib.dom.d.ts. There, the type of window is everything the Window interface lists, joined with & to every global name (typeof globalThis), an intersection like the ones in the previous lesson. featureFlags is in neither. The code still runs and prints true; TypeScript just hasn't been told about the property.

Window is an interface, so you can declare it again and your declaration joins the browser's:

1declare global {2  interface Window {3    featureFlags: { newCheckout: boolean };4  }5}6 7window.featureFlags = { newCheckout: true };8console.log(window.featureFlags.newCheckout);9//                 ^?

Lines 1 to 5 are a declare global block. declare means "this only describes something; it makes no code". global means the declarations inside go into the global scope, where the browser's Window lives. Lines 2 to 4 declare interface Window with one property, featureFlags, and it merges with the browser's Window. Line 7 sets the flags, and line 8 prints true with no errors. The query on line 9 shows (property) Window.featureFlags: { newCheckout: boolean; }.

Why the declare global wrapper? In a project, a file with import or export is a module, and most files are (Why modules covers them). This site checks every example as a module too, even without those lines. Names declared in a module stay in that module. Leave the wrapper out and see:

1interface Window {2  featureFlags: { newCheckout: boolean };3}4 5window.featureFlags = { newCheckout: true };

Lines 1 to 3 make a new Window that only this file can see. The browser's Window is unchanged, so line 5 gets the same error as before: Property 'featureFlags' does not exist. In a project file with no import or export, declarations are global already, so interface Window { … } alone is enough there. You'll often see that in a file named like global.d.ts; a .d.ts file holds only types.

Merging a namespace into a function

In JavaScript, a function is an object, so it can have properties of its own (the Function objects lesson shows how). TypeScript's older way to describe that is a namespace. A namespace is a named group of values, written namespace Shop { … }. Names inside it marked export can be read from outside, like Shop.currency. Namespaces come from before JavaScript had modules. Today modules do their job, but you'll still meet namespaces in libraries' type files.

Namespaces with the same name merge, like interfaces:

1namespace Shop {2  export const currency = "$";3}4namespace Shop {5  export function label(price: number) {6    return currency + price.toFixed(2);7  }8}9 10console.log(Shop.label(3));

Lines 1 to 3 make a Shop namespace with an exported currency. Lines 4 to 8 declare Shop again and add a label function. The two join, so line 6 can use currency from the first block, and line 10 prints $3.00. Only exported names join: without export on line 2, line 6 would get Cannot find name 'currency'.

These namespace examples have no Edit & run. A namespace with values is one of the few TypeScript features that turns into JavaScript code instead of being removed, and this site's editor only removes types. Node.js's built-in TypeScript support refuses them for the same reason. They're still checked here, and you'll see the JavaScript the compiler writes below.

A namespace can also merge with a function of the same name. The namespace's exported names become the function's properties:

1function formatPrice(price: number) {2  return formatPrice.currency + price.toFixed(2);3}4namespace formatPrice {5  export const currency = "$";6}7 8console.log(formatPrice(3));9//          ^?10console.log(formatPrice.currency);

Lines 1 to 3 declare a function formatPrice that reads formatPrice.currency. Lines 4 to 6 declare a namespace with the same name and an exported currency. The two merge, so line 2 is allowed. Line 8 prints $3.00. The query on line 9 gets a two-line answer, function formatPrice(price: number): string and namespace formatPrice: one name, two things. Line 10 reads the property and prints $.

Two rules for this merge:

• The namespace comes after the function. Put it first and TypeScript says A namespace declaration cannot be located prior to a class or function with which it is merged.
• Both are in the same file, and only the namespace's exported names become properties.

Here is the JavaScript the TypeScript compiler writes for the example, which you can run:

function formatPrice(price) {
  return formatPrice.currency + price.toFixed(2);
}
(function (formatPrice) {
  formatPrice.currency = "$";
})(formatPrice || (formatPrice = {}));
console.log(formatPrice(3));
console.log(formatPrice.currency);

Lines 1 to 3 are the function, with its types removed. Lines 4 to 6 are the namespace: a function that runs right away and sets formatPrice.currency to "$". The function is an object, so that just adds a property. Line 7 prints $3.00, and line 8 prints $.

In your own code you rarely need a namespace for this. TypeScript understands a property you set on a function in the same place you declare it:

1function formatPrice(price: number) {2  return formatPrice.currency + price.toFixed(2);3}4formatPrice.currency = "$";5 6console.log(formatPrice(3));

Line 4 sets formatPrice.currency, and TypeScript adds currency to the function's type, so line 2 has no error. This is plain JavaScript once the types are removed, so it runs anywhere. Line 6 prints $3.00.

Why type aliases don't merge

A type alias, written type Settings = { … }, gives a name to one type, finished when you write it. An interface is open: more declarations can add to it. You met this difference in Type aliases & interfaces. Try both with the same two property lists:

1interface Settings {2  theme: string;3}4interface Settings {5  fontSize: number;6}7 8const settings: Settings = { theme: "dark", fontSize: 16 };9console.log(settings.theme, settings.fontSize);

Two interfaces join, with no errors. Two type aliases get Duplicate identifier 'Settings' on lines 1 and 4. "Identifier" means a name, so this says the name Settings is used twice. TypeScript then uses only the first Settings, which has no font size, so lines 8 and 9 get errors too. Two names joined with & is the type alias way to build on a type: give the first part its own name, BaseSettings, and make Settings from it with & (the Intersection types lesson covers &).

The table below compares the two. Read each row as a question, then the answer for an interface and for a type alias.

So when a library wants you to add to one of its types, it uses an interface. When you want a type nobody can add to by accident, a type alias does that.

Typing a custom cart event

A shop page can tell its other parts that the cart changed by sending an event on window. A CustomEvent carries extra data in its detail property (the Custom events lesson covers them). Here is a listener and the event, with no types added:

1window.addEventListener("cart:updated", (event) => {2  console.log(`Cart has ${event.detail.count} items`);3});4 5window.dispatchEvent(new CustomEvent("cart:updated", { detail: { count: 3 } }));

Line 1 listens for "cart:updated". Line 2 reads event.detail.count. Line 5 sends the event with a count of 3. The code runs and prints Cart has 3 items, but TypeScript marks line 2, on purpose here: Property 'detail' does not exist on type 'Event'. TypeScript doesn't know this event name, so it treats the event as a plain Event, which has no detail.

How does addEventListener know what an event is? The browser's types have an interface, WindowEventMap, that lists event names and their event types. For "click" it says a PointerEvent. WindowEventMap is an interface, so you can merge your own event into it:

1declare global {2  interface WindowEventMap {3    "cart:updated": CustomEvent<{ count: number }>;4  }5}6 7window.addEventListener("cart:updated", (event) => {8//                                       ^?9  console.log(`Cart has ${event.detail.count} items`);10});11 12window.dispatchEvent(new CustomEvent("cart:updated", { detail: { count: 3 } }));

Lines 1 to 5 add "cart:updated" to WindowEventMap. Its type, CustomEvent<{ count: number }>, means a custom event whose detail is { count: number }; the angle brackets fill in the type of detail (the Generic functions lesson explains them). Line 7 listens, and the query on line 8 shows the event is now that CustomEvent. Line 9 reads event.detail.count with no error, and the code prints Cart has 3 items.

This is the pattern behind "libraries let you add to their types": the library ships an interface, and your declaration joins it. Now sort some declarations by what TypeScript says about them:

Common mix-ups

Merging only changes types. Here is a Window property that is declared but never set:

1declare global {2  interface Window {3    featureFlags: { newCheckout: boolean };4  }5}6 7console.log(window.featureFlags);

Lines 1 to 5 tell TypeScript that window.featureFlags exists, so line 7 has no error. But nothing ever sets it, and the types are removed before the code runs, so line 7 prints undefined. A declaration is a promise you still have to keep.

• "The second interface replaces the first." No. Every declaration's properties are kept, and the one type has all of them.
• "When two declarations disagree, the later one wins." No. A property named twice must have the same type each time. Otherwise the later one gets Subsequent property declarations must have the same type.
• "declare global puts the property on window." No. It only describes the property. Your code still has to set it, or it's undefined.
• "interface Window in any file adds to the browser's Window." No. In a module, it makes a new Window for that file. Wrap it in declare global.
• "Type aliases merge too." No. A second type alias with the same name is a Duplicate identifier error. Use an interface, or a new name and &.
• "Merging changes the JavaScript that runs." No. Interfaces are removed completely. Only namespaces with values turn into code.

The table below lists what can merge. Read each row as: this pair of declarations with one name, does it merge, and what TypeScript does.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1interface Product {2  name: string;3}4interface Product {5  price: number;6}7interface Product {8  inStock: boolean;9}

1interface Product {2  name: string;3}4interface Product {5  price: number;6}7interface Product {8  inStock: boolean;9}10 11const tea: Product = { name: "Tea", price: 3, inStock: true };12console.log(Object.keys(tea).length);

interface CartItem {
  name: string;
  price: number;
}
interface CartItem {
  price: string;
  quantity: number;
}

1interface CartItem {2  name: string;3  price: number;4}5interface CartItem {6  quantity: number;7}

1window.cartCount = 3;2console.log(window.cartCount);

1declare global {2  interface Window {3    cartCount: number;4  }5}6 7window.cartCount = 3;8console.log(window.cartCount);

1type Settings = {2  theme: string;3};4type Settings = {5  fontSize: number;6};7 8const settings: Settings = { theme: "dark", fontSize: 16 };

1interface Settings {2  theme: string;3}4interface Settings {5  fontSize: number;6}7 8const settings: Settings = { theme: "dark", fontSize: 16 };

1window.addEventListener("wishlist:added", (event) => {2  console.log(`Added ${event.detail.name}`);3});4 5window.dispatchEvent(new CustomEvent("wishlist:added", { detail: { name: "Tea" } }));

1declare global {2  interface WindowEventMap {3    "wishlist:added": CustomEvent<{ name: string }>;4  }5}6 7window.addEventListener("wishlist:added", (event) => {8  console.log(`Added ${event.detail.name}`);9});10 11window.dispatchEvent(new CustomEvent("wishlist:added", { detail: { name: "Tea" } }));

1function formatPrice(price: number): string {2  return formatPrice.currency + price.toFixed(2);3}4 5console.log(formatPrice(4));

1function formatPrice(price: number): string {2  return formatPrice.currency + price.toFixed(2);3}4formatPrice.currency = "$";5 6console.log(formatPrice(4));

Check your understanding

For each question, ask which declarations share a name, and whether that kind of declaration can merge. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Interfaces with the same name join into one type with every property from each declaration.
• A property named in two declarations must have the same type, or the later one gets an error.
• To add to a global type like Window or WindowEventMap from a module, declare it again inside declare global.
• A declaration only describes. Your code still has to set the property it promises.
• A namespace after a function with the same name gives the function properties. Namespaces with values become real code.
• Two type aliases or two classes with one name don't merge: TypeScript marks both with Duplicate identifier.

Coming next: Classes in TypeScript. It types a class's fields, constructor, and methods, and shows the parameter-property shortcut.