Fix 'Could not find a declaration file for module' in TypeScript

By the end of this page, you will understand why TypeScript can run a JavaScript package but still fail to find its type declarations, how package.json fields such as main and types affect module resolution, and how to properly publish a TypeScript package so consumers can import it by package name without errors.

TypeScript resolves runtime code and type information separately.

Node.js only cares about the JavaScript entry point, usually defined by the main field in package.json:

{
  "main": "dist/index.js"
}

That is enough for Node to execute your package.

TypeScript, however, also needs to know where the declaration files are. Declaration files are the .d.ts files that describe the public API of your package.

If TypeScript can load the JavaScript file but cannot find matching type declarations, it treats the module as any and shows an error like:

Could not find a declaration file for module 'package-name'

Even if dist/index.d.ts exists, TypeScript may not automatically use it when importing the package by name unless the package metadata clearly points to it.

The usual fix is to add a types field to package.json:

{
  "main": 
   

Think of a package like a book:

• main tells Node.js which chapter to start reading.
• types tells TypeScript where the table of contents and glossary are.

Without types, Node can still read the book, but TypeScript cannot understand the meaning of the terms inside it.

So your package may run fine but still be invisible to the type system.

A TypeScript-friendly package usually includes both JavaScript output and declaration files.

Correct package.json

{
  "name": "@ts-stack/di",
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

Basic library structure

dist/
  index.js
  index.d.ts

Example library code

Source:

// src/index.ts
export class Injector {
  get(name: string): string {
    return `Resolved: ${name}`;
  }
}

Compiled output:

// dist/index.js
export class  {
  () {
     ;
  }
}

Consider this package metadata:

{
  "main": "dist/index.js"
}

And this import:

import { Injector } from '@ts-stack/di';

What happens step by step

1. TypeScript sees the package import @ts-stack/di.
2. It looks inside that package's package.json.
3. It finds main: "dist/index.js", so it knows which JavaScript file is the runtime entry.
4. It then tries to find type declarations for the package.
5. If there is no types field and TypeScript cannot confidently resolve the declarations for the package entry, it reports that the module has no declaration file.
6. Because types are missing, the package is treated as any.

Why direct file import may appear to work

import { Injector } from '/path/to/node_modules/@ts-stack/di/dist/index.js';

In this case, TypeScript is resolving a specific file path. Since sits next to , TypeScript can often match them directly.

This issue appears often when building and publishing TypeScript libraries.

Shared internal packages

A team publishes a utility package used by several services:

import { formatCurrency } from '@company/utils';

If types is missing, every TypeScript project importing it loses autocomplete and type safety.

Open-source npm libraries

A library author publishes compiled JavaScript and .d.ts files, but forgets to include the declaration entry in package.json. JavaScript users are fine, but TypeScript users get errors.

Monorepos

In a workspace setup, one package may depend on another local package. If the dependent package is not configured with correct declaration metadata, imports work at runtime but fail in editors and builds.

SDKs and API clients

Packages that expose classes, functions, and config objects rely heavily on declaration files so users can discover the API without reading source code.

In real projects, developers usually combine several patterns to make package typing reliable.

Explicit package entry points

The most common setup is:

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

This makes the package entry predictable.

Build declarations automatically

In tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "outDir": "dist"
  }
}

This ensures .d.ts files are generated whenever the package builds.

Export from a single public entry file

Developers usually re-export public APIs from src/index.ts:

1. Setting only main

Broken:

{
  "main": "dist/index.js"
}

Why it fails:

• Node can run the package.
• TypeScript may not know where the declarations start.

Fix:

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

2. Forgetting to generate declaration files

Broken tsconfig.json:

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

Fix:

{
   
     
     
  

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

Key rules

• main points to the runtime JavaScript entry.
• types points to the TypeScript declaration entry.
• Generate declarations with declaration: true.
• Publish the .d.ts files along with .js files.
• Prefer importing the package name, not internal file paths.

Minimal tsconfig.json

{
  "compilerOptions": {
    "declaration": true,
    "outDir": "dist"
  }
}

Minimal package structure

Why does Node.js work but TypeScript fails?

Node.js only needs JavaScript to run. TypeScript also needs declaration files for type checking.

Is main enough for a TypeScript package?

No. main is for runtime code. You should also provide types for declarations.

Do I need @types/... for my own TypeScript library?

Usually no. If your package generates and publishes its own .d.ts files, that is enough.

What should the types field point to?

It should point to your package's public declaration entry, usually something like dist/index.d.ts.

Can TypeScript infer types from JavaScript automatically?

Sometimes partially, but published packages should not rely on that. Declaration files are the standard solution.

What is the difference between types and typings?

They serve the same purpose. types is the common modern field name.

Why does importing dist/index.js work?

Because TypeScript can often match that exact file with a nearby . That does not mean the package itself is configured correctly.

• TypeScript declaration files (.d.ts) — These describe the types exported by a package.
• Module resolution — This explains how TypeScript and Node locate imports.
• package.json fields — Fields like main, types, and exports control package behavior.
• Publishing npm packages — Correct packaging ensures built files and declarations are included.
• TypeScript compiler options — Options such as declaration and outDir affect generated output.
• @types packages — These provide types for JavaScript libraries that do not ship their own declarations.
• Barrel files (index.ts) — These create a single public entry point for exports.