TypeScript module augmentation for extending third-party types

<p>I need to extend types from a third-party library (fastify, express, next.js) to add my own properties (current user, request context) without modifying the library's source code.</p>

<p>Module augmentation to extend existing types:</p> <div class="highlight"><pre><span></span><code><span class="c1">// Extend FastAPI/Express request with custom properties:</span> <span class="c1">// types/express.d.ts</span> <span class="k">import</span><span class="w"> </span><span class="s1">'express'</span><span class="p">;</span> <span class="kr">declare</span><span class="w"> </span><span class="nx">module</span><span class="w"> </span><span class="s1">'express'</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kd">interface</span><span class="w"> </span><span class="nx">Request</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">user</span><span class="o">?:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">id</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span><span class="w"> </span><span class="nx">email</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span><span class="w"> </span><span class="nx">role</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span><span class="w"> </span><span class="p">};</span> <span class="w"> </span><span class="nx">requestId</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span> <span class="w"> </span><span class="nx">startTime</span><span class="o">:</span><span class="w"> </span><span class="kt">number</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="p">}</span> <span class="c1">// types/next.d.ts -- extend Next.js App context</span> <span class="k">import</span><span class="w"> </span><span class="kr">type</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">NextApiRequest</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">'next'</span><span class="p">;</span> <span class="kr">declare</span><span class="w"> </span><span class="nx">module</span><span class="w"> </span><span class="s1">'next'</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kd">interface</span><span class="w"> </span><span class="nx">NextApiRequest</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">user?</span><span class="o">:</span><span class="w"> </span><span class="kt">AuthUser</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="p">}</span> <span class="c1">// Extend environment variables type:</span> <span class="c1">// types/env.d.ts</span> <span class="kr">declare</span><span class="w"> </span><span class="nx">namespace</span><span class="w"> </span><span class="nx">NodeJS</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kd">interface</span><span class="w"> </span><span class="nx">ProcessEnv</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">DATABASE_URL</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span> <span class="w"> </span><span class="nx">REDIS_URL</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span> <span class="w"> </span><span class="nx">OPENAI_API_KEY</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">;</span> <span class="w"> </span><span class="nx">NODE_ENV</span><span class="o">:</span><span class="w"> </span><span class="s1">'development'</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="s1">'production'</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="s1">'test'</span><span class="p">;</span> <span class="w"> </span><span class="p">}</span> <span class="p">}</span> <span class="c1">// Extend window for analytics:</span> <span class="c1">// types/global.d.ts</span> <span class="kr">declare</span><span class="w"> </span><span class="nb">global</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="kd">interface</span><span class="w"> </span><span class="nx">Window</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">analytics</span><span class="o">?:</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">track</span><span class="o">:</span><span class="w"> </span><span class="p">(</span><span class="nx">event</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="nx">props?</span><span class="o">:</span><span class="w"> </span><span class="kt">Record</span><span class="o">&lt;</span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="nx">unknown</span><span class="o">&gt;</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="ow">void</span><span class="p">;</span> <span class="w"> </span><span class="nx">identify</span><span class="o">:</span><span class="w"> </span><span class="p">(</span><span class="nx">userId</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="ow">void</span><span class="p">;</span> <span class="w"> </span><span class="p">};</span> <span class="w"> </span><span class="p">}</span> <span class="p">}</span> <span class="c1">// Usage -- TypeScript knows about your additions:</span> <span class="nx">app</span><span class="p">.</span><span class="nx">use</span><span class="p">((</span><span class="nx">req</span><span class="p">,</span><span class="w"> </span><span class="nx">res</span><span class="p">,</span><span class="w"> </span><span class="nx">next</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nx">req</span><span class="p">.</span><span class="nx">requestId</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">crypto</span><span class="p">.</span><span class="nx">randomUUID</span><span class="p">();</span><span class="w"> </span><span class="c1">// TypeScript knows this exists</span> <span class="w"> </span><span class="nx">next</span><span class="p">();</span> <span class="p">});</span> <span class="kd">const</span><span class="w"> </span><span class="nx">dbUrl</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">DATABASE_URL</span><span class="p">;</span><span class="w"> </span><span class="c1">// TypeScript knows it's string not string | undefined</span> </code></pre></div> <p>Key points: - Module augmentation must be in a .d.ts file or a module file with import/export - Use declare module 'package-name' to augment existing modules - declare global for augmenting global types (window, process.env) - The file must be included in tsconfig.json include or typeRoots - Do not use augmentation to add methods that don't exist -- only types for existing runtime behavior</p>