A module using CommonJS patterns uses module.exports to describe the exported values. For example, here is a module which exports a function and a numerical constant:
\njsconst maxInterval = 12;\n\nfunction getArrayLength(arr) {\n return arr.slice;\n}\n\nmodule.exports = {\n getArrayLength,\n maxInterval,\n};
This can be described by the following .d.ts:
\ntsexport function getArrayLength(arr: any[]): number;\nexport const maxInterval: 12;
The TypeScript playground can show you the .d.ts equivalent for JavaScript code. You can try it yourself here.
The .d.ts syntax intentionally looks like ES Modules syntax.\nES Modules was ratified by TC39 in 2019, while it has been available via transpilers for a long time, however if you have a JavaScript codebase using ES Modules:
\njsexport function getArrayLength(arr) {\n return arr.length;\n}
This would have the following .d.ts equivalent:
\ntsexport function getArrayLength(arr: any[]): number;
In CommonJS you can export any value as the default export, for example here is a regular expression module:
\n\njsmodule.exports = /hello( world)?/;
Which can be described by the following .d.ts:
\n\ntsconst helloWorld: RegExp;\nexport default helloWorld;
Or a number:
\n\njsmodule.exports = 3.142;
\ntsconst pi: number;\nexport default pi;
One style of exporting in CommonJS is to export a function.\nBecause a function is also an object, then extra fields can be added are included in the export.
\n\njsfunction getArrayLength(arr) {\n return arr.slice;\n}\ngetArrayLength.maxInterval = 12;\n\nmodule.exports = getArrayLength;
Which can be described with:
\n\ntsexport default function getArrayLength(arr: any[]): number;\nexport const maxInterval: 12;
Note that using export default in your .d.ts files requires esModuleInterop: true to work.\nIf you can’t have esModuleInterop: true in your project, such as when you’re submitting a PR to Definitely Typed, you’ll have to use the export= syntax instead. This older syntax is harder to use but works everywhere.\nHere’s how the above example would have to be written using export=:
\ntsdeclare function getArrayLength(arr: any[]): number;\ndeclare namespace getArrayLength {\n declare const maxInterval: 12;\n}\n\nexport = getArrayLength;
See Module: Functions for details of how that works, and the Modules reference page.
\nThere are many ways to import a module in modern consuming code:
\n\ntsconst fastify = require(\"fastify\");\nconst { fastify } = require(\"fastify\");\nimport fastify = require(\"fastify\");\nimport * as Fastify from \"fastify\";\nimport { fastify, FastifyInstance } from \"fastify\";\nimport fastify from \"fastify\";\nimport fastify, { FastifyInstance } from \"fastify\";
Covering all of these cases requires the JavaScript code to actually support all of these patterns.\nTo support many of these patterns, a CommonJS module would need to look something like:
\n\njsclass FastifyInstance {}\n\nfunction fastify() {\n return new FastifyInstance();\n}\n\nfastify.FastifyInstance = FastifyInstance;\n\n// Allows for { fastify }\nfastify.fastify = fastify;\n// Allows for strict ES Module support\nfastify.default = fastify;\n// Sets the default export\nmodule.exports = fastify;
You may want to provide a type for JavaScript code which does not exist
\n\njsfunction getArrayMetadata(arr) {\n return {\n length: getArrayLength(arr),\n firstObject: arr[0],\n };\n}\n\nmodule.exports = {\n getArrayMetadata,\n};
This can be described with:
\n\ntsexport type ArrayMetadata = {\n length: number;\n firstObject: any | undefined;\n};\nexport function getArrayMetadata(arr: any[]): ArrayMetadata;
This example is a good case for using generics to provide richer type information:
\n\ntsexport type ArrayMetadata<ArrType> = {\n length: number;\n firstObject: ArrType | undefined;\n};\n\nexport function getArrayMetadata<ArrType>(\n arr: ArrType[]\n): ArrayMetadata<ArrType>;
Now the type of the array propagates into the ArrayMetadata type.
The types which are exported can then be re-used by consumers of the modules using either import or import type in TypeScript code or JSDoc imports.
Trying to describe the runtime relationship of JavaScript code can be tricky.\nWhen the ES Module-like syntax doesn’t provide enough tools to describe the exports then you can use namespaces.
For example, you may have complex enough types to describe that you choose to namespace them inside your .d.ts:
\nts// This represents the JavaScript class which would be available at runtime\nexport class API {\n constructor(baseURL: string);\n getInfo(opts: API.InfoRequest): API.InfoResponse;\n}\n\n// This namespace is merged with the API class and allows for consumers, and this file\n// to have types which are nested away in their own sections.\ndeclare namespace API {\n export interface InfoRequest {\n id: string;\n }\n\n export interface InfoResponse {\n width: number;\n height: number;\n }\n}
To understand how namespaces work in .d.ts files read the .d.ts deep dive.
You can use export as namespace to declare that your module will be available in the global scope in UMD contexts:
\ntsexport as namespace moduleName;
To give you an idea of how all these pieces can come together, here is a reference .d.ts to start with when making a new module
\nts// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]\n// Project: [~THE PROJECT NAME~]\n// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>\n\n/*~ This is the module template file. You should rename it to index.d.ts\n *~ and place it in a folder with the same name as the module.\n *~ For example, if you were writing a file for \"super-greeter\", this\n *~ file should be 'super-greeter/index.d.ts'\n */\n\n/*~ If this module is a UMD module that exposes a global variable 'myLib' when\n *~ loaded outside a module loader environment, declare that global here.\n *~ Otherwise, delete this declaration.\n */\nexport as namespace myLib;\n\n/*~ If this module exports functions, declare them like so.\n */\nexport function myFunction(a: string): string;\nexport function myOtherFunction(a: number): number;\n\n/*~ You can declare types that are available via importing the module */\nexport interface SomeType {\n name: string;\n length: number;\n extras?: string[];\n}\n\n/*~ You can declare properties of the module using const, let, or var */\nexport const myField: number;
The layout of your declaration files should mirror the layout of the library.
\nA library can consist of multiple modules, such as
\nmyLib\n +---- index.js\n +---- foo.js\n +---- bar\n +---- index.js\n +---- baz.js\nThese could be imported as
\n\njsvar a = require(\"myLib\");\nvar b = require(\"myLib/foo\");\nvar c = require(\"myLib/bar\");\nvar d = require(\"myLib/bar/baz\");
Your declaration files should thus be
\n@types/myLib\n +---- index.d.ts\n +---- foo.d.ts\n +---- bar\n +---- index.d.ts\n +---- baz.d.ts\nIf you are planning on submitting these changes to DefinitelyTyped for everyone to also use, then we recommend you:
\n\n\n\n
\n- Create a new folder in
\nnode_modules/@types/[libname]- Create an
\nindex.d.tsin that folder, and copy the example in- See where your usage of the module breaks, and start to fill out the index.d.ts
\n- When you’re happy, clone DefinitelyTyped/DefinitelyTyped and follow the instructions in the README.
\n
Otherwise
\n\n","headings":[{"value":"Comparing JavaScript to an example DTS","depth":2},{"value":"Common CommonJS Patterns","depth":2},{"value":"Default Exports","depth":3},{"value":"Handling Many Consuming Import","depth":2},{"value":"Types in Modules","depth":2},{"value":"Namespaces in Module Code","depth":3},{"value":"Optional Global Usage","depth":3},{"value":"Reference Example","depth":2},{"value":"Library file layout","depth":3},{"value":"Testing your types","depth":3}],"frontmatter":{"permalink":"/docs/handbook/declaration-files/templates/module-d-ts.html","title":"Modules .d.ts","disable_toc":null,"oneline":null}},"prev":null,"next":null},"pageContext":{"id":"modules-.d.ts","slug":"/docs/handbook/declaration-files/templates/module-d-ts.html","repoPath":"/packages/documentation/copy/en/declaration-files/templates/module.d.ts.md","lang":"en","modifiedTime":"2020-08-07T17:00:36.335Z"}}}\n
\n- Create a new file in the root of your source tree:
\n[libname].d.ts- Add
\ndeclare module \"[libname]\" { }- Add the template inside the braces of the declare module, and see where your usage breaks
\n