TypeScript declare module: Type Untyped npm Packages

Summary

Pixel shares a guide to using TypeScript declare module to add local type definitions for untyped npm packages without relying on DefinitelyTyped. It explains module augmentation, why declaration files need an import or export, and how to configure TypeScript 5.x and 6.0 to recognize them.

DEV Community

TypeScript declare module Augmentation in 2026: Adding Types to Untyped npm Packages Without DefinitelyTyped

TypeScript declare module Augmentation in 2026: Adding Types to Untyped npm Packages Without DefinitelyTyped This article was written with the assistance of AI, under human supervision and review. TypeScript projects frequently depend on npm packages that ship no type definitions. The package works at runtime, but every import triggers compiler errors. The @types namespace exists for popular libraries, yet thousands of smaller packages remain untyped. When npm install @types/your-package returns a 404, developers face a choice: abandon type safety for that dependency or write declarations manually. The standard advice points to DefinitelyTyped, a central repository where contributors submit type definitions for review and publication. This process takes weeks and requires ongoing maintenance as the underlying package evolves. For internal tools, proprietary packages, or rapidly changing APIs, DefinitelyTyped becomes a bottleneck rather than a solution. TypeScript provides declare module for local augmentation, which adds types directly in the consuming project. The declaration file lives alongside application code, versioned in the same repository, and remains under direct control. Changes to the package API require only a local edit, no pull request to an external repository. This post demonstrates the mechanics of declare module, the critical distinction between global scripts and module augmentation, and the setup required to make TypeScript recognize local type declarations. The patterns here apply to TypeScript 5.x and 6.0, with references to the official tsconfig documentation for configuration fields. Key Takeaways declare module creates type definitions for untyped npm packages without submitting to DefinitelyTyped. A declaration file MUST contain at least one import or export statement to function as module augmentation; files without either become global scripts where declare module creates new ambient modules that do not merge with existing types. Place declaration files in a types/ directory and configure typeRoots in tsconfig.json to include that path (the typeRoots field accepts an array of directory paths relative to the tsconfig file). Interface declarations inside declare module merge with existing package types, while type aliases and classes overwrite them completely. The types field in package.json points to the main declaration file when bundling types with a published package (as documented in Publishing Declaration Files). Understanding Module Augmentation vs Ambient Declarations TypeScript distinguishes between two uses of declare module: ambient module declarations and module augmentation. Ambient declarations create new modules from scratch, typically for global scripts or libraries that define global variables. Module augmentation extends existing modules by merging new declarations with the original type definitions. The difference determines whether TypeScript merges the new declarations or treats them as separate definitions. When a file contains no import or export statements, TypeScript treats it as a global script. A declare module in a global script creates a new ambient module. If the module name matches an installed package, the ambient declaration shadows the package's original types rather than augmenting them. When a file includes at least one import or export statement, TypeScript treats it as a module. A declare module in a module file becomes augmentation. The compiler merges the new declarations with the package's existing types, preserving original definitions while adding new members. This distinction surfaces in a common failure mode: developers write a declaration file with declare module "some-package", place it in the project, but omit any import or export. The file becomes a global script. The declared module takes precedence over the actual package types, and existing typed members disappear. Adding a single export {} at the top of the file converts it to a module, enablin...
TypeScript declare module: Type Untyped npm Packages
Powered by Readybot.io

The latest from Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …