What Do Type Declarations Look Like?
Let's say you write some code like this:
const k = Math.max(5, 6); const j = Math.mixProperty 'mix' does not exist on type 'Math'.(7, 8);Property 'mix' does not exist on type 'Math'.
How did TypeScript know that
max was present but not
mix, even though
Math's implementation wasn't part of your code?
The answer is that there are declaration files describing these built-in objects. A declaration file provides a way to declare the existence of some types or values without actually providing implementations for those values.
TypeScript has two main kinds of files.
.ts files are implementation files that contain types and executable code.
These are the files that produce
.js outputs, and are where you'd normally write your code.
.d.ts files are declaration files that contain only type information.
These files don't produce
.js outputs; they are only used for typechecking.
We'll learn more about how to write our own declaration files later.
Built-in Type Definitions
This includes things like methods and properties of built-in types like
function, top-level names like
Object, and their associated types.
By default, TypeScript also includes types for things available when running inside the browser, such as
document; these are collectively referred to as the DOM APIs.
TypeScript names these declaration files with the pattern
If you navigate into a file with that name, you can know that you're dealing with some built-in part of the platform, not user code.
For example, the
This is one function of the
target compiler setting.
TypeScript helps with this problem by varying which
lib files are included by default based on your
For example, if
ES5, you will see an error if trying to use the
startsWith method, because that method is only available in
ES6 or later.
lib setting allows more fine-grained control of which built-in declaration files are considered available in your program.
See the documentation page on lib for more information.
For non-built-in APIs, there are a variety of ways you can get declaration files. How you do this depends on exactly which library you're getting types for.
If a library you're using is published as an npm package, it may include type declaration files as part of its distribution already. You can read the project's documentation to find out, or simply try importing the package and see if TypeScript is able to automatically resolve the types for you.
If you're a package author considering bundling type definitions with your package, you can read our guide on bundling type definitions.
The DefinitelyTyped repository is a centralized repo storing declaration files for thousands of libraries. The vast majority of commonly-used libraries have declaration files available on DefinitelyTyped.
Definitions on DefinitelyTyped are also automatically published to npm under the
The name of the types package is always the same as the name of the underlying package itself.
For example, if you installed the
react npm package, you can install its corresponding types by running
npm install --save-dev @types/react
TypeScript automatically finds type definitions under
node_modules/@types, so there's no other step needed to get these types available in your program.
Your Own Definitions
In the uncommon event that a library didn't bundle its own types and didn't have a definition on DefinitelyTyped, you can write a declaration file yourself. See the appendix Writing Declaration Files for a guide.
If you want to silence warnings about a particular module without writing a declaration file, you can also quick declare the module as type
any by putting an empty declaration for it in a
.d.ts file in your project.
For example, if you wanted to use a module named
some-untyped-module without having definitions for it, you would write:
declare module "some-untyped-module";