Broadly speaking, the way you structure your declaration file depends on how the library is consumed.\nThere are many ways of offering a library for consumption in JavaScript, and you’ll need to write your declaration file to match it.\nThis guide covers how to identify common library patterns, and how to write declaration files which correspond to that pattern.
\nEach type of major library structuring pattern has a corresponding file in the Templates section.\nYou can start with these templates to help you get going faster.
\nFirst, we’ll review the kinds of libraries TypeScript declaration files can represent.\nWe’ll briefly show how each kind of library is used, how it is written, and list some example libraries from the real world.
\nIdentifying the structure of a library is the first step in writing its declaration file.\nWe’ll give hints on how to identify structure both based on its usage and its code.\nDepending on the library’s documentation and organization, one might be easier than the other.\nWe recommend using whichever is more comfortable to you.
\nA global library is one that can be accessed from the global scope (i.e. without using any form of import).\nMany libraries simply expose one or more global variables for use.\nFor example, if you were using jQuery, the $ variable can be used by simply referring to it:
\nts$(() => { console.log('hello!'); } );
You’ll usually see guidance in the documentation of a global library of how to use the library in an HTML script tag:
\n\nhtml<script src=\"http://a.great.cdn.for/someLib.js\"></script>
Today, most popular globally-accessible libraries are actually written as UMD libraries (see below).\nUMD library documentation is hard to distinguish from global library documentation.\nBefore writing a global declaration file, make sure the library isn’t actually UMD.
\nGlobal library code is usually extremely simple.\nA global “Hello, world” library might look like this:
\n\njsfunction createGreeting(s) {\n return \"Hello, \" + s;\n}
or like this:
\n\njswindow.createGreeting = function(s) {\n return \"Hello, \" + s;\n}
When looking at the code of a global library, you’ll usually see:
\nvar statements or function declarationswindow.someNamedocument or window existYou won’t see:
\nrequire or definevar fs = require(\"fs\");define(...)require or import the libraryBecause it’s usually easy to turn a global library into a UMD library, very few popular libraries are still written in the global style.\nHowever, libraries that are small and require the DOM (or have no dependencies) may still be global.
\nThe template file global.d.ts defines an example library myLib.\nBe sure to read the “Preventing Name Conflicts” footnote.
Some libraries only work in a module loader environment.\nFor example, express only works in Node.js and must be loaded using the CommonJS require function.
ECMAScript 2015 (also known as ES2015, ECMAScript 6, and ES6), CommonJS, and RequireJS have similar notions of importing a module.\nIn JavaScript CommonJS (Node.js), for example, you would write
\n\njsvar fs = require(\"fs\");
In TypeScript or ES6, the import keyword serves the same purpose:
\ntsimport fs = require(\"fs\");
You’ll typically see modular libraries include one of these lines in their documentation:
\n\njsvar someLib = require('someLib');
or
\n\njsdefine(..., ['someLib'], function(someLib) {\n\n});
As with global modules, you might see these examples in the documentation of a UMD module, so be sure to check the code or documentation.
\nModular libraries will typically have at least some of the following:
\nrequire or defineimport * as a from 'b'; or export c;exports or module.exportsThey will rarely have:
\nwindow or globalMany popular Node.js libraries are in the module family, such as express, gulp, and request.
A UMD module is one that can either be used as module (through an import), or as a global (when run in an environment without a module loader).\nMany popular libraries, such as Moment.js, are written this way.\nFor example, in Node.js or using RequireJS, you would write:
\n\ntsimport moment = require(\"moment\");\nconsole.log(moment.format());
whereas in a vanilla browser environment you would write:
\n\njsconsole.log(moment.format());
UMD modules check for the existence of a module loader environment.\nThis is an easy-to-spot pattern that looks something like this:
\n\njs(function (root, factory) {\n if (typeof define === \"function\" && define.amd) {\n define([\"libName\"], factory);\n } else if (typeof module === \"object\" && module.exports) {\n module.exports = factory(require(\"libName\"));\n } else {\n root.returnExports = factory(root.libName);\n }\n}(this, function (b) {
If you see tests for typeof define, typeof window, or typeof module in the code of a library, especially at the top of the file, it’s almost always a UMD library.
Documentation for UMD libraries will also often demonstrate a “Using in Node.js” example showing require,\nand a “Using in the browser” example showing using a <script> tag to load the script.
Most popular libraries are now available as UMD packages.\nExamples include jQuery, Moment.js, lodash, and many more.
\nThere are three templates available for modules,\nmodule.d.ts, module-class.d.ts and module-function.d.ts.
Use module-function.d.ts if your module can be called like a function:
\njsvar x = require(\"foo\");\n// Note: calling 'x' as a function\nvar y = x(42);
Be sure to read the footnote “The Impact of ES6 on Module Call Signatures”
\nUse module-class.d.ts if your module can be constructed using new:
\njsvar x = require(\"bar\");\n// Note: using 'new' operator on the imported variable\nvar y = new x(\"hello\");
The same footnote applies to these modules.
\nIf your module is not callable or constructable, use the module.d.ts file.
A module plugin changes the shape of another module (either UMD or module).\nFor example, in Moment.js, moment-range adds a new range method to the moment object.
For the purposes of writing a declaration file, you’ll write the same code whether the module being changed is a plain module or UMD module.
\nUse the module-plugin.d.ts template.
A global plugin is global code that changes the shape of some global.\nAs with global-modifying modules, these raise the possibility of runtime conflict.
\nFor example, some libraries add new functions to Array.prototype or String.prototype.
Global plugins are generally easy to identify from their documentation.
\nYou’ll see examples that look like this:
\n\njsvar x = \"hello, world\";\n// Creates new methods on built-in types\nconsole.log(x.startsWithHello());\n\nvar y = [1, 2, 3];\n// Creates new methods on built-in types\nconsole.log(y.reverseAndSort());
Use the global-plugin.d.ts template.
A global-modifying module alters existing values in the global scope when they are imported.\nFor example, there might exist a library which adds new members to String.prototype when imported.\nThis pattern is somewhat dangerous due to the possibility of runtime conflicts,\nbut we can still write a declaration file for it.
Global-modifying modules are generally easy to identify from their documentation.\nIn general, they’re similar to global plugins, but need a require call to activate their effects.
You might see documentation like this:
\n\njs// 'require' call that doesn't use its return value\nvar unused = require(\"magic-string-time\");\n/* or */\nrequire(\"magic-string-time\");\n\nvar x = \"hello, world\";\n// Creates new methods on built-in types\nconsole.log(x.startsWithHello());\n\nvar y = [1, 2, 3];\n// Creates new methods on built-in types\nconsole.log(y.reverseAndSort());
Use the global-modifying-module.d.ts template.
There are several kinds of dependencies your library might have.\nThis section shows how to import them into the declaration file.
\nIf your library depends on a global library, use a /// <reference types=\"...\" /> directive:
\nts/// <reference types=\"someLib\" />\n\nfunction getThing(): someLib.thing;
If your library depends on a module, use an import statement:
\ntsimport * as moment from \"moment\";\n\nfunction getThing(): moment;
If your global library depends on a UMD module, use a /// <reference types directive:
\nts/// <reference types=\"moment\" />\n\nfunction getThing(): moment;
If your module or UMD library depends on a UMD library, use an import statement:
\ntsimport * as someLib from 'someLib';
Do not use a /// <reference directive to declare a dependency to a UMD library!
Note that it’s possible to define many types in the global scope when writing a global declaration file.\nWe strongly discourage this as it leads to possible unresolvable name conflicts when many declaration files are in a project.
\nA simple rule to follow is to only declare types namespaced by whatever global variable the library defines.\nFor example, if the library defines the global value ‘cats’, you should write
\n\ntsdeclare namespace cats {\n interface KittySettings { }\n}
But not
\n\nts// at top-level\ninterface CatsKittySettings { }
This guidance also ensures that the library can be transitioned to UMD without breaking declaration file users.
\nSome plugins add or modify top-level exports on existing modules.\nWhile this is legal in CommonJS and other loaders, ES6 modules are considered immutable and this pattern will not be possible.\nBecause TypeScript is loader-agnostic, there is no compile-time enforcement of this policy, but developers intending to transition to an ES6 module loader should be aware of this.
\nMany popular libraries, such as Express, expose themselves as a callable function when imported.\nFor example, the typical Express usage looks like this:
\n\ntsimport exp = require(\"express\");\nvar app = exp();
In ES6 module loaders, the top-level object (here imported as exp) can only have properties;\nthe top-level module object is never callable.\nThe most common solution here is to define a default export for a callable/constructable object;\nsome module loader shims will automatically detect this situation and replace the top-level object with the default export.
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\n