---
title: Declaration Files
slug: /declarations
description: "A declaration file is a .flow file that declares the types of a module separately from its implementation. Use one to add types to a module you cannot or do not want to annotate directly."
---

A **declaration file** is a `.flow` file (e.g. `Misc.js.flow`) that declares the types for a module separately from its `.js` implementation. When a `.flow` file sits next to an implementation file of the same name, Flow ignores the implementation and reads the declaration file instead. Use a declaration file to add types to a module you cannot or do not want to annotate directly — for example, generated code, code that must remain plain JavaScript, or a module whose types you want to override.

## What's a Declaration File? {#toc-what-s-a-declaration-file}

Let's look at a more general, and sometimes more convenient way to
declare types for modules: `.flow` files.

There are two possible use cases, depending on whether an implementation file exists
or not.

In the first case, the exported types of a module are declared in a _declaration
file_ `<FILENAME>.flow`, that is located in the same directory as the corresponding _implementation
file_ `<FILENAME>`. The declaration file completely shadows the colocated
implementation. In other words, Flow will completely ignore `<FILENAME>` and just
read `<FILENAME>.flow` instead.

In the second case, the implementation file is missing entirely. `<FILENAME>.flow`
is treated as if it is named `<FILENAME>`.

Declaration files can shadow both `.js` and `.json` implementation files; the corresponding declaration-file extensions are `.js.flow` and `.json.flow`, respectively.

Now let's see an example of the first case documented above. Suppose we have the
following code in a file `src/LookBeforeYouLeap.js`:

```js
import { isLeapYear } from "./Misc";
if (isLeapYear("2020")) console.log("Yay!");
```

and suppose that `src/Misc.js` has an incompatible implementation of `isLeapYear`:

```js flow-check
export function isLeapYear(year: number): boolean {
  return year % 4 == 0; // yeah, this is approximate
}
```

If we now create a declaration file `src/Misc.js.flow`, the declarations in it
will be used instead of the code in `src/Misc.js`. Let's say we have the
following declarations in `src/Misc.js.flow`.

> NOTE: The syntax for declarations in a declaration file is the same as we've seen in
>       [Creating Library Definitions section](../libdefs/creation.md).

```js flow-check
declare export function isLeapYear(year: string): boolean;
```

What do you think will happen?

Right, the `isLeapYear` call in `src/LookBeforeYouLeap.js` will typecheck, since
the `year` parameter expects a `string` in the declaration file.

As this example shows, declaration files must be written with care: it is up
to the programmer to ensure they are correct, otherwise they may hide type
errors.


## Inlining declarations in regular code {#toc-inlining-declarations-in-regular-code}

Sometimes it is useful to make declarations inline, as part of the source of
an implementation file.

In the following example, say you want to finish writing
the function `fooList` without bothering to mock up its dependencies first: a
function `foo` that takes a `number` and returns a `string`, and a class
`List` that has a `map` method. You can do this by including declarations for
`List` and `foo`:

```js flow-check
declare class List<T> {
  map<U>(f: (x: T) => U): List<U>;
}
declare function foo(n: number): string;

function fooList(ns: List<number>): List<string> {
  return ns.map(foo);
}
```

Just don't forget to replace the declarations with proper implementations.

## Generating declaration files {#toc-generating-declaration-files}

The `flow` binary itself does not emit declaration files. The separate [`flow-api-translator`](https://www.npmjs.com/package/flow-api-translator) npm package fills this gap: given a Flow source file, it produces a `.js.flow` declaration file or a TypeScript `.d.ts` file. This is the closest equivalent to TypeScript's `tsc --declaration` and `--emitDeclarationOnly` modes.

## See Also {#toc-see-also}

- [Library Definitions](../libdefs/index.md) — declaring types for third-party npm packages
- [Module Types](../types/modules.md) — importing and exporting types between modules
- [`.flowconfig [declarations]`](../config/declarations.md) — configuring declaration mode for third-party code
