Export TypeScript .d.ts files as an external module definition
This module is a naïve string-based approach at generating bundles from the .d.ts declaration files generated by a TypeScript compiler.
The main use-case is generating definition for npm/bower modules written in TypeScript (commonjs/amd) so the TypeScript code should following the external-module pattern (using
⚠️ Experimental; use with care.
This module was born out of necessity and frustration. It is a little hacky but at least it seems to work..
- Original code was extracted from an ad-hoc Grunt-task so for now it is fully synchronous with no error feedback.
- It works by line-by-line string operations so please report any edge-cases.
- Get it from npm:
npm install dts-bundle
- Compile your modules with the TypeScript compiler of your choice with the
--outDirflags (and probably
tsc src/index.ts --declaration --module commonjs --target es5 --outDir build
dts-bundle(you can run it from cli, see "Command line" section.
Let's assume the project is called
cool-project and the main module is
build/index.js with a
var dts = ;dts;
This will traverse all references and imports for the .d.ts files of your sub-modules and write
build/cool-project.d.ts with the bundle of all 'local' imports.
- Bonus points if you link the generated definition in your package.json's (or bower.json)
Using this makes the definition findable for tooling, for example the TypeScript Definitions package manager (from v0.6.x) can auto-link these into
tsd.d.ts bundle file.
Example of all options:
var opts =// Required// name of module likein package.json// - used to declare module & import/requirename: 'cool-project'// path to entry-point (generated .d.ts file for main module)// if you want to load all .d.ts files from a path recursively you can use "path/project/**/*.d.ts"// ^ *** Experimental, TEST NEEDED, see "All .d.ts files" section// - either relative or absolutemain: 'build/index.d.ts'// Optional// base directory to be used for discovering type declarations (i.e. from this project itself)// - default: dirname of mainbaseDir: 'build'// path of output file. Is relative from baseDir but you can use absolute paths.// if starts with "~/" then is relative to current path. See// ^ *** Experimental, TEST NEEDED// - default: "<baseDir>/<name>.d.ts"out: 'dist/cool-project.d.ts'// include typings outside of the 'baseDir' (i.e. like node.d.ts)// - default: falseexternals: false// reference external modules as <reference path="..." /> tags *** Experimental, TEST NEEDED// - default: falsereferenceExternals: false// filter to exclude typings, either a RegExp or a callback. match path relative to opts.baseDir// - RegExp: a match excludes the file// - function: (file:String, external:Boolean) return true to exclude, false to allow// - always use forward-slashes (even on Windows)// - default: *pass*exclude: /^defs\/$/// delete all source typings (i.e. "<baseDir>/**/*.d.ts")// - default: falseremoveSource: false// newline to use in output filenewline: osEOL// indentation to use in output file// - default 4 spacesindent: ' '// prefix for rewriting module names// - default ''prefix: '__'// separator for rewriting module 'path' names// - default: forward slash (like sub-modules)separator: '/'// enable verbose mode, prints detailed info about all references and includes/excludes// - default: falseverbose: false// emit although included files not found. See "Files not found" section.// *** Experimental, TEST NEEDED// - default: falseemitOnIncludedFileNotFound: false// emit although no included files not found. See "Files not found" section.// *** Experimental, TEST NEEDED// - default: falseemitOnNoIncludedFileNotFound: false// output d.ts as designed for module folder. (no declare modules)outputAsModuleFolder: false// path to file that contains the header// // insert a header in output file. i.e.:// - default: nullheaderPath: "path/to/header/file"// text of the the header// doesn't work with headerPath// // insert a header in output file. i.e.:// - default: ''headerTex: "";// require modulevar dts = ;// run itdts;
Experimental - Test needed - https://github.com/TypeStrong/dts-bundle/issues/29
You can bundle the definitions from for all files contained on a directory, and children directories.
If you set
main parameter to some path ended with
dts-bundle load all .d.ts files and generate a bundle.
dts-bundle builds a temporally file with export of the rest of the files. You can see it on verbose mode: i.e:
// ## temporally main file ##;;;;;;;;;;;;;;;;;
dts-bundle processes this file. When finish the temporally file is deleted.
NPM introduced support for in-package typings, it is done by adding typings key into package.json file, which should refer to the typings file. when this is the case, the d.ts file is threated as module folder, and declare module is not allowed.
outputAsModuleFolder. When using this option output d.ts will be compatible with module folder. which means, no declare module are used, and all internal references are removed as they are merged into the output d.ts.
Files not found.
Experimental - Test needed -
dts-bundle expects to find all references for all modules. Goes over all files referenced and tries to load each file to get the definitions,
when he loads all files
dts-bundle determines if include each one in the final bundle. If some file is not found dts-bundle doesn't emit the
result file. You could want to emit the result file although some file are not found. The file not found can be an included or exclued file in
the bundle then you have two options to control these cases:
emitOnIncludedFileNotFound. When there are files not found and these file should be included in the bundle,
dts-bundlewrites the output file if
emitOnIncludedFileNotFoundis true. This allow you to have external file definitions that you will load by other way in your final project.
emitOnNoIncludedFileNotFound. When there are files not found and these file shouldn't be included in the bundle,
dts-bundlewrites the output file if
emitOnNoIncludedFileNotFoundis true. This allow you don't to include external typings in your temporally output compile path.
Experimental - Test needed -
bundle function return an object that implement this interface:
You can use the return value to determine if continue your gulp or grunt task or stop and emit an error.
You can use
dts-bundle from command line, its allow you use it from npm scripts see #13 .
You have to install it using -g:
npm install dts-bundle -g
You can use the following options:
Usage: dts-bundle [options] Options: -h, --help output usage information -V, --version output the version number --configJson <value> path to json config file. Load it first and override options with additional parameters --name <value> name of module likein package.json *required --main <value> path to entry-point (see documentation) *required --baseDir [value] base directory to be used for discovering type declarations --out [value] path of output file. Is relative from baseDir but you can use absolute paths. --externals include typings outside of the "baseDir" (i.e. like node.d.ts) --referenceExternals reference external modules as <reference path="..." /> tags --removeSource delete all source typings (i.e. "<baseDir>/**/*.d.ts") --newline [style] newline style to use in output file => unix|windows|currentOsDefault --prefix [value] prefix for rewriting module names --verbose enable verbose mode, prints detailed info about all references and includes/excludes --emitOnIncludedFileNotFound emit although included files not found. See readme "Files not found" section. --emitOnNoIncludedFileNotFound emit although no included files not found. See readme "Files not found" section. --outputAsModuleFolder output as module folder format (no declare module) . See readme "Module folders" section. --headerPath [value] path to file that contains the header --headerText [value] text of the header. Doesn't work with headerPath.
dts-bundle --name cool-project --main build/output/index.d.ts
You can load config from a json file:
// dts-bundle.json file
Run this way:
dts-bundle --configJson dts-bundle.json
And can override properties:
dts-bundle --configJson dts-bundle.json --name coolest
- add feature to create a DefinitelyTyped header (using
- add feature to auto-update package.json/bower.json with the definition link
- find time to implement a parser based solution
- run IO asyncronous
- 0.4.x Several features.
- CLI command
- Support not found file (
- Output relative to current path using "~/"
- referenceExternals option
- All files feature using
- Return a object with the result
- Add Header using
- 0.3.x - Support es6 module syntax & rewrite by TypeScript
- 0.2.x - Fixed bugs & added many options (thanks @poelstra)
- 0.1.x - First release
They are very welcome. Beware this module is a quick hack-job so good luck!
- Martin Poelstra (@poelstra): Exclude 'external' typings, optional debug output, improved configurability.
Licensed under the MIT license.