Should You Ditch .d.ts Files? Exploring .ts‑Only TypeScript Development

Inspired by a post from Matt Pocock questioning the need for .d.ts files, this article asks whether developers should replace them with regular .ts files.

.d.ts Files' Purpose

.d.ts files are not useless; they provide type descriptions for JavaScript code, acting as strict blueprints that trace back to 2012 and are inspired by header files, IDL, and JSDoc.

.d.ts files are primarily used to describe the types of JavaScript code.

They contain only declarations. For example, a declaration for an add function looks like this:

// Declaration (.d.ts)
export function add(num1: number, num2: number): number;

And the implementation in a .ts file is:

// Implementation (.ts)
export function add(num1: number, num2: number): number {
  return num1 + num2;
}

The implementation shows the actual logic, while the declaration only describes the signature.

Replacement Plan with .ts Files

Instead of separate .d.ts files, you can place both declarations and implementations in a single .ts file (e.g., add.ts ), which is equivalent to having add.d.ts and add.js .

For libraries, keeping generated .d.ts files alongside compiled JavaScript is still more efficient because consumers only need the type declarations.

It is recommended to generate these files automatically by adjusting tsconfig.json and package.json :

tsconfig.json : add "declaration": true to enable .d.ts generation.

{
  "compilerOptions": {
    "declaration": true,
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

package.json : set the "types" field to point to the generated .d.ts file.

{
  "name": "stop using d.ts",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": { "build": "tsc" }
}

Conclusion

Everything you can achieve with a .d.ts file can also be done inside a .ts file, using constructs like declare global {} for global declarations.

When using .ts files directly, you avoid issues such as skipLibCheck being set to true , which can hide type errors in custom declaration files.

In most cases (about 99%), using .ts files is preferable, improving developer experience and reducing the risk of type mismatches.