TypeScript Module Patterns

Organize TypeScript code with ES modules, barrel exports, path aliases, and declaration files

When to Use

• Structuring a TypeScript project's import/export architecture
• Setting up barrel files (index.ts re-exports) for clean public APIs
• Configuring path aliases to avoid deep relative imports
• Creating or consuming declaration files (.d.ts)

Instructions

1. Use named exports over default exports for better refactoring and tree-shaking:

// user.ts
export interface User {
  id: string;
  name: string;
}
export function createUser(name: string): User {
  /* ... */
}

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

2. Barrel files — re-export from

   index.ts

   to create clean module boundaries:

// features/auth/index.ts
export { AuthProvider } from './auth-provider';
export { useAuth } from './use-auth';
export type { AuthState, AuthAction } from './types';

// Consumer imports from the module, not internal files
import { AuthProvider, useAuth } from '@/features/auth';

3. Configure path aliases in

   tsconfig.json

   :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/db/*": ["src/db/*"],
      "@/lib/*": ["src/lib/*"]
    }
  }
}

Mirror in your bundler config (Next.js, Vite, etc.) so runtime resolution matches TypeScript's.

4. export type

   for type-only exports — prevents runtime import of type-only modules:

export type { User, Post } from './types';
export { createUser } from './user';

5. import type

   for type-only imports:

import type { User } from './types';
import { createUser } from './user';

Enable

verbatimModuleSyntax

in tsconfig to enforce this distinction.

6. Declaration files (.d.ts) — provide types for JavaScript modules:

// legacy-module.d.ts
declare module 'legacy-module' {
  export function doWork(input: string): number;
  export interface Config {
    verbose: boolean;
  }
}

7. Namespace imports for modules with many exports:

import * as Schema from '@/db/schema';

const user = Schema.users;
const post = Schema.posts;

8. Avoid circular imports — if module A imports from B and B imports from A:

   • Extract shared types into a separate module C
   • Use

     import type

     when only types are needed (type imports are erased and do not cause runtime circularity)
   • Restructure to unidirectional dependencies

9. Package entry points — configure

   exports

   in

   package.json

   for library projects:

{
  "exports": {
    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
    "./utils": { "types": "./dist/utils.d.ts", "import": "./dist/utils.js" }
  }
}

Details

TypeScript modules follow the ES module standard. Each file with a top-level

import

or

export

is a module; files without them are scripts (global scope).

verbatimModuleSyntax

(recommended): Forces you to use

import type

for type-only imports and

export type

for type-only re-exports. This eliminates ambiguity about which imports are erased during compilation.

Barrel file trade-offs:

• Pros: Clean public API, consumers do not depend on internal file structure
• Cons: Can defeat tree-shaking in some bundlers (import from barrel loads entire module), can create large import chains
• Best practice: Use barrels at feature boundaries, not for every directory

Path aliases require bundler sync: TypeScript's

paths

only affect type checking. The runtime module resolver (Node.js, Vite, webpack) must also be configured to resolve the same aliases.

moduleResolution

options:

• node

  — traditional Node.js resolution (index.ts, package.json main)

• node16

  /

  nodenext

  — Node.js ESM resolution (requires file extensions in imports)

• bundler

  — modern bundler resolution (Vite, webpack, esbuild). Best choice for most frontend projects

Trade-offs:

• Barrel files improve DX but can hurt bundle size — profile with your bundler's analysis tool
• Path aliases improve readability but add configuration overhead in every tool that processes imports

• verbatimModuleSyntax

  catches real bugs but requires existing code to be updated with

  import type

Source

https://typescriptlang.org/docs/handbook/modules.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.