Modules and Declaration Files

The 6-Hour "Module Not Found" Nightmare

Friday, 3:45 PM. Deploy time for our new feature. I ran npm run build:

Error: Cannot find module '@utils/helpers'
Error: Cannot find module '@services/api'
Error: Cannot find module '@components/Button'
... 47 more errors

The code worked perfectly on my machine. TypeScript compiled fine locally. But CI/CD failed.

After 6 hours of debugging, I found the issue:

// tsconfig.json on my machine
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["src/utils/*"],
      "@services/*": ["src/services/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

TypeScript resolved the paths fine. But tsc doesn't rewrite import paths in the output. The compiled JavaScript still had:

import { formatDate } from '@utils/helpers';  // Node can't resolve this!

Node.js doesn't understand TypeScript's path mapping. Production was broken.

The fix required understanding modules deeply:

// package.json
{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils/index.js",
    "./services": "./dist/services/index.js",
    "./components": "./dist/components/index.js"
  }
}

And switching to relative imports for critical paths:

// From this:
import { api } from '@services/api';

// To this:
import { api } from '../services/api';

Result: Build worked. Deploy succeeded. Learned modules the hard way.

This article covers module systems, path resolution, and declaration files – the unglamorous foundation that prevents 6-hour debugging sessions.

---

ES Modules

Modern JavaScript module system.

Basic Export/Import

// user.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export function createUser(name: string, email: string): User {
  return {
    id: generateId(),
    name,
    email
  };
}

export const DEFAULT_USER: User = {
  id: '0',
  name: 'Guest',
  email: '[email protected]'
};

// app.ts
import { User, createUser, DEFAULT_USER } from './user';

const user: User = createUser('John', '[email protected]');
console.log(DEFAULT_USER);

Default Exports

// config.ts
export default {
  apiUrl: 'https://api.example.com',
  timeout: 5000
};

// app.ts
import config from './config';

console.log(config.apiUrl);

Mixed Exports

// utils.ts
export function formatDate(date: Date): string {
  return date.toISOString();
}

export function parseDate(str: string): Date {
  return new Date(str);
}

export default {
  formatDate,
  parseDate
};

// app.ts
import utils from './utils';              // Default import
import { formatDate } from './utils';     // Named import

formatDate(new Date());
utils.formatDate(new Date());

---

CommonJS

Node.js traditional module system.

Basic Module.exports

// user.ts
interface User {
  id: string;
  name: string;
}

function createUser(name: string): User {
  return { id: generateId(), name };
}

module.exports = {
  createUser
};

// Or
export = { createUser };

// app.ts
const { createUser } = require('./user');

// Or with TypeScript
import user = require('./user');
const { createUser } = user;

---

Module Resolution

How TypeScript finds modules.

Classic Strategy (Deprecated)

// Looks for:
// 1. /root/src/folder/moduleA.ts
// 2. /root/src/folder/moduleA.d.ts
// 3. /root/src/moduleA.ts
// 4. /root/src/moduleA.d.ts
// 5. /root/moduleA.ts
// ... and so on

Node Strategy (Default)

import { something } from './module';

// Relative import looks for:
// 1. ./module.ts
// 2. ./module.tsx
// 3. ./module.d.ts
// 4. ./module/package.json (check "types" field)
// 5. ./module/index.ts
// 6. ./module/index.tsx
// 7. ./module/index.d.ts

import { something } from 'lodash';

// Non-relative import looks in node_modules:
// 1. node_modules/lodash.ts
// 2. node_modules/lodash.tsx
// 3. node_modules/lodash.d.ts
// 4. node_modules/lodash/package.json (check "types")
// 5. node_modules/lodash/index.d.ts
// 6. node_modules/@types/lodash/index.d.ts

---

Path Mapping

Configure custom module paths.

Basic Path Mapping

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

// Before:
import { Button } from '../../../components/Button';
import { formatDate } from '../../../utils/formatDate';

// After:
import { Button } from '@components/Button';
import { formatDate } from '@utils/formatDate';

Wildcard Mapping

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "*": ["src/*", "node_modules/*"]
    }
  }
}

Warning: TypeScript resolves these for type checking, but doesn't rewrite imports in output. Need a bundler (webpack, rollup) or runtime loader.

---

Declaration Files (.d.ts)

Type definitions without implementation.

Basic Declaration File

// math.d.ts
export function add(a: number, b: number): number;
export function subtract(a: number, b: number): number;

export interface Calculator {
  add(a: number, b: number): number;
  subtract(a: number, b: number): number;
}

// app.ts
import { add, Calculator } from './math';

const result = add(5, 3);  // TypeScript knows the signature

Ambient Declarations

// global.d.ts
declare global {
  interface Window {
    myApp: {
      version: string;
      config: Record<string, unknown>;
    };
  }
}

export {};

// app.ts
window.myApp.version = '1.0.0';  // TypeScript knows this exists

Module Augmentation

// express-custom.d.ts
import 'express';

declare module 'express' {
  export interface Request {
    user?: {
      id: string;
      email: string;
    };
  }
}

// app.ts
import { Request } from 'express';

function handler(req: Request) {
  console.log(req.user?.id);  // TypeScript knows about custom property
}

---

@types Packages

DefinitelyTyped community type definitions.

Installing @types

npm install --save-dev @types/node
npm install --save-dev @types/express
npm install --save-dev @types/lodash

How @types Works

// You write:
import express from 'express';

// TypeScript looks for:
// 1. node_modules/express/package.json -> "types" field
// 2. node_modules/express/index.d.ts
// 3. node_modules/@types/express/index.d.ts  // ← Found here!

Custom Types

// src/types/custom.d.ts
declare module 'my-untyped-library' {
  export function doSomething(value: string): number;
  export class MyClass {
    constructor(value: string);
    getValue(): string;
  }
}

// app.ts
import { doSomething, MyClass } from 'my-untyped-library';

const result = doSomething('hello');  // TypeScript knows it returns number

---

Triple-Slash Directives

Special comments for compiler instructions.

Reference Types

/// <reference types="node" />

// Makes Node.js types available
process.env.NODE_ENV = 'production';

Reference Path

/// <reference path="./global.d.ts" />

// Include specific declaration file

Reference Lib

/// <reference lib="es2020" />
/// <reference lib="dom" />

// Include specific library types

---

Namespace vs Modules

Namespaces (Old Style)

namespace Utils {
  export function formatDate(date: Date): string {
    return date.toISOString();
  }
  
  export function parseDate(str: string): Date {
    return new Date(str);
  }
}

// Usage
Utils.formatDate(new Date());

Avoid namespaces in modern TypeScript. Use modules instead.

Modules (Modern)

// utils.ts
export function formatDate(date: Date): string {
  return date.toISOString();
}

export function parseDate(str: string): Date {
  return new Date(str);
}

// app.ts
import * as Utils from './utils';

Utils.formatDate(new Date());

---

Real-World Patterns

1. Barrel Exports

// components/Button/Button.tsx
export const Button = (props) => { /* ... */ };

// components/Input/Input.tsx
export const Input = (props) => { /* ... */ };

// components/Modal/Modal.tsx
export const Modal = (props) => { /* ... */ };

// components/index.ts (barrel)
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';

// app.ts
// Instead of:
import { Button } from './components/Button/Button';
import { Input } from './components/Input/Input';
import { Modal } from './components/Modal/Modal';

// Use:
import { Button, Input, Modal } from './components';

2. Type-Only Imports

// Imports only types (removed at runtime)
import type { User } from './types';
import type { ApiResponse } from './api';

// Mixed import
import { formatDate, type DateFormat } from './utils';

3. Dynamic Imports

// Lazy loading
async function loadModule() {
  const module = await import('./heavy-module');
  module.doSomething();
}

// With types
async function loadUser(id: string) {
  const { User } = await import('./user');
  return new User(id);
}

---

Project Structure

Monorepo Structure

packages/
  core/
    src/
      index.ts
    package.json
    tsconfig.json
  ui/
    src/
      components/
        index.ts
      index.ts
    package.json
    tsconfig.json
  api/
    src/
      routes/
      services/
      index.ts
    package.json
    tsconfig.json
tsconfig.base.json
package.json

Shared Types

// packages/core/src/types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

// packages/core/src/index.ts
export type { User } from './types/user';

// packages/ui/src/UserProfile.tsx
import type { User } from '@myapp/core';

function UserProfile({ user }: { user: User }) {
  // ...
}

---

Common Mistakes I Made

1. Forgetting to Export

// utils.ts
function formatDate(date: Date): string {  // Not exported!
  return date.toISOString();
}

// app.ts
import { formatDate } from './utils';  // ✗ Error: Module has no exported member 'formatDate'

Fix: Add export

export function formatDate(date: Date): string {
  return date.toISOString();
}

2. Circular Dependencies

// user.ts
import { getOrders } from './order';

export class User {
  getOrders() {
    return getOrders(this.id);
  }
}

// order.ts
import { User } from './user';

export function getOrders(userId: string) {
  // Uses User type
}
// ✗ Circular dependency!

Fix: Extract shared types

// types.ts
export interface User {
  id: string;
}

// user.ts
import { User } from './types';

// order.ts
import { User } from './types';

3. Path Mapping Without Build Tool

// tsconfig.json
{
  "paths": {
    "@utils/*": ["src/utils/*"]
  }
}

import { formatDate } from '@utils/helpers';
// Works in TypeScript, but compiled output still has '@utils/helpers'
// Node.js can't resolve it!

Fix: Use bundler (webpack, rollup, esbuild) or relative imports for Node.js

---

Your Challenge

Build a modular plugin system:

// TODO: Define plugin interface

interface Plugin {
  name: string;
  version: string;
  init(): void;
  execute(data: unknown): unknown;
}

// TODO: Create declaration file for plugin loader

// plugin-loader.d.ts
declare module 'plugin-loader' {
  export function loadPlugin(path: string): Promise<Plugin>;
  export function registerPlugin(plugin: Plugin): void;
  export function getPlugins(): Plugin[];
}

// TODO: Create example plugins with proper exports

// plugins/logger/index.ts
// plugins/validator/index.ts
// plugins/transformer/index.ts

// TODO: Create barrel export for all plugins

// plugins/index.ts

// Requirements:
// 1. Proper module structure
// 2. Type-safe plugin interface
// 3. Declaration files for extensibility
// 4. Barrel exports for clean imports
// 5. Documentation with JSDoc

---

Key Takeaways

1. ES modules - modern standard with import/export

2. CommonJS - Node.js traditional with require/module.exports

3. Module resolution - Classic vs Node strategies

4. Path mapping - custom module paths (needs bundler for output)

5. Declaration files - .d.ts for types without implementation

6. @types packages - community type definitions

7. Barrel exports - clean imports from directories

8. Type-only imports - import type for types

---

What I Learned

The 6-hour module nightmare taught me: TypeScript's module resolution is for type checking, not runtime.

The mistake:

{
  "paths": {
    "@utils/*": ["src/utils/*"]
  }
}

TypeScript was happy. Types checked. Compiled without errors.

But the output:

import { formatDate } from '@utils/helpers';  // Node.js: "What's @utils?"

TypeScript doesn't rewrite import paths. It only uses them for type resolution.

The fix depends on the environment:

For bundled apps (webpack/vite/rollup):

• Path mapping works - bundler resolves it

• Keep the convenience

For Node.js libraries:

• Use relative imports

• Or set up package.json exports

• Runtime must resolve paths

The lesson: TypeScript modules are two systems:

1. Compile-time: TypeScript's type resolution

2. Runtime: JavaScript's module loader

They must both work. TypeScript helps with #1, but you own #2.

Know your target runtime. Test the compiled output. Module errors are silent until runtime.

---

Next: TypeScript Configuration

In the next article, we'll explore tsconfig.json and compiler options. You'll learn how a single compiler flag saved us from 200+ potential runtime errors.