{"id":13661242,"url":"https://github.com/TypeStrong/dts-bundle","last_synced_at":"2025-04-24T23:32:11.110Z","repository":{"id":48670221,"uuid":"21108670","full_name":"TypeStrong/dts-bundle","owner":"TypeStrong","description":"Export TypeScript .d.ts files as an external module definition","archived":false,"fork":false,"pushed_at":"2022-02-06T21:27:39.000Z","size":138,"stargazers_count":309,"open_issues_count":35,"forks_count":57,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-06T13:11:18.436Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TypeStrong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-22T23:33:21.000Z","updated_at":"2025-03-20T13:46:34.000Z","dependencies_parsed_at":"2022-08-27T07:31:45.206Z","dependency_job_id":null,"html_url":"https://github.com/TypeStrong/dts-bundle","commit_stats":null,"previous_names":["grunt-ts/dts-bundle"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypeStrong%2Fdts-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypeStrong%2Fdts-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypeStrong%2Fdts-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypeStrong%2Fdts-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TypeStrong","download_url":"https://codeload.github.com/TypeStrong/dts-bundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250185637,"owners_count":21389069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T05:01:31.461Z","updated_at":"2025-04-24T23:32:10.604Z","avatar_url":"https://github.com/TypeStrong.png","language":"TypeScript","readme":"# dts-bundle\n\n[![Build Status](https://travis-ci.org/TypeStrong/dts-bundle.svg)](https://travis-ci.org/TypeStrong/dts-bundle) [![NPM version](https://badge.fury.io/js/dts-bundle.svg)](http://badge.fury.io/js/dts-bundle) [![Dependency Status](https://david-dm.org/TypeStrong/dts-bundle.svg)](https://david-dm.org/TypeStrong/dts-bundle) [![devDependency Status](https://david-dm.org/TypeStrong/dts-bundle/dev-status.svg)](https://david-dm.org/TypeStrong/dts-bundle#info=devDependencies)\n\n\u003e Export TypeScript .d.ts files as an external module definition\n\nThis module is a naïve string-based approach at generating bundles from the .d.ts declaration files generated by a TypeScript compiler.\n\nThe 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 `import/export`'s and `--outDir`).\n\n:warning: Experimental; use with care.\n\nThis module was born out of necessity and frustration. It is a little hacky but at least it seems to work..\n\n- Original code was extracted from an ad-hoc Grunt-task so for now it is fully synchronous with no error feedback.\n- It works by line-by-line string operations so please [report](https://github.com/grunt-ts/dts-bundle/issues) any edge-cases.\n\n\n## Usage\n\n1) Get it from npm:\n\n````\nnpm install dts-bundle\n````\n\n2) Compile your modules with the TypeScript compiler of your choice with the `--declaration` and `--outDir` flags (and probably `--module commonjs` too).\n\nSomething like:\n\n````shell\ntsc src/index.ts --declaration --module commonjs --target es5 --outDir build\n````\n\n3) Run `dts-bundle` (you can run it from cli, see \"Command line\" section.\n\nLet's assume the project is called `cool-project` and the main module is `build/index.js` with a `build/index.d.ts`:\n\n````js\nvar dts = require('dts-bundle');\n\ndts.bundle({\n\tname: 'cool-project',\n\tmain: 'build/index.d.ts'\n});\n````\n\nThis 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.\n\n**Optional:**\n\n4) Bonus points if you link the generated definition in your package.json's (or bower.json) `typescript` element:\n\n````json\n{\n\t\"name\": \"cool-project\",\n\t\"version\": \"0.1.3\",\n\n\t\"typescript\": {\n\t\t\"definition\": \"build/cool-project.d.ts\"\n\t}\n}\n````\n\nUsing this makes the definition findable for tooling, for example the [TypeScript Definitions package manager](https://github.com/DefinitelyTyped/tsd) (from v0.6.x) can auto-link these into `tsd.d.ts` bundle file.\n\n\n### Wrappers\n\nThere is also a Grunt plugin [grunt-dts-bundle](https://www.github.com/grunt-ts/grunt-dts-bundle) that goes well with Grunt based compilers, like [grunt-ts](https://www.github.com/grunt-ts/grunt-ts) or [grunt-typescript](https://github.com/k-maru/grunt-typescript).\n\n\n## Options\n\nExample of all options:\n\n````js\nvar opts = {\n\n\t// Required\n\n\t// name of module likein package.json\n\t// - used to declare module \u0026 import/require\n\tname: 'cool-project',\n\t// path to entry-point (generated .d.ts file for main module)\n    // if you want to load all .d.ts files from a path recursively you can use \"path/project/**/*.d.ts\"\n    //  ^ *** Experimental, TEST NEEDED, see \"All .d.ts files\" section \n\t// - either relative or absolute\n\tmain: 'build/index.d.ts',\n\n\t// Optional\n\n\t// base directory to be used for discovering type declarations (i.e. from this project itself)\n\t// - default: dirname of main\n\tbaseDir: 'build',\n\t// path of output file. Is relative from baseDir but you can use absolute paths. \n    // if starts with \"~/\" then is relative to current path. See https://github.com/TypeStrong/dts-bundle/issues/26\n    //  ^ *** Experimental, TEST NEEDED    \n\t// - default: \"\u003cbaseDir\u003e/\u003cname\u003e.d.ts\"\n\tout: 'dist/cool-project.d.ts',\n\t// include typings outside of the 'baseDir' (i.e. like node.d.ts)\n\t// - default: false\n\texternals: false,\n\t// reference external modules as \u003creference path=\"...\" /\u003e tags *** Experimental, TEST NEEDED\n\t// - default: false\n\treferenceExternals: false,\n\t// filter to exclude typings, either a RegExp or a callback. match path relative to opts.baseDir\n\t// - RegExp: a match excludes the file\n\t// - function: (file:String, external:Boolean) return true to exclude, false to allow\n\t// - always use forward-slashes (even on Windows)\n\t// - default: *pass*\n\texclude: /^defs\\/$/,\n  \t// delete all source typings (i.e. \"\u003cbaseDir\u003e/**/*.d.ts\")\n\t// - default: false\n\tremoveSource: false,\n\t// newline to use in output file\n\tnewline: os.EOL,\n\t// indentation to use in output file\n\t// - default 4 spaces\n\tindent: '\t',\n\t// prefix for rewriting module names\n\t// - default ''\n\tprefix: '__',\n\t// separator for rewriting module 'path' names\n\t// - default: forward slash (like sub-modules)\n\tseparator: '/',\n\t// enable verbose mode, prints detailed info about all references and includes/excludes\n\t// - default: false\n\tverbose: false,\n    // emit although included files not found. See \"Files not found\" section. \n    // *** Experimental, TEST NEEDED\n    // - default: false \n    emitOnIncludedFileNotFound: false,\n    // emit although no included files not found. See \"Files not found\" section. \n    // *** Experimental, TEST NEEDED\n    // - default: false     \n    emitOnNoIncludedFileNotFound: false,    \n    // output d.ts as designed for module folder. (no declare modules)\n    outputAsModuleFolder: false,\n    // path to file that contains the header\n    // // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header\n    // - default: null\n    headerPath: \"path/to/header/file\",\n    // text of the the header\n    // doesn't work with headerPath\n    // // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header\n    // - default: ''\n    headerTex: \"\" \n};\n\n// require module\nvar dts = require('dts-bundle');\n\n// run it\ndts.bundle(opts);\n````\n\n### All `.d.ts` files\n\nExperimental - Test needed - https://github.com/TypeStrong/dts-bundle/issues/29\n\nYou can bundle the definitions from for all files contained on a directory, and children directories.\nIf you set `main` parameter to some path ended with `**/*.d.ts` then `dts-bundle` load all .d.ts files and generate a bundle.\nInternally `dts-bundle` builds a temporally file with export of the rest of the files. You can see it on verbose mode: i.e:\n\n```` typescript\n// ## temporally main file ##\nexport * from './Core/Bootstrap';\nexport * from './Core/ChangeDetection';\nexport * from './Core/ControllerDecorator';\nexport * from './Core/LifeCycle\\LifeCycleHooks';\nexport * from './Decorators/Component';\nexport * from './Decorators/Input';\nexport * from './Decorators/Output';\nexport * from './Directives/ngPropertyBinding';\nexport * from './Events/EventEmitter';\nexport * from './Expressions/ExpressionParser';\nexport * from './Expressions/Ng1Lexer\\Lexer';\nexport * from './Ng2Emulation';\nexport * from './Templates/HtmlParser\\Parser';\nexport * from './Templates/HtmlParser\\ParserRule';\nexport * from './Templates/HtmlParser\\Rules\\EventBindingRule';\nexport * from './Templates/HtmlParser\\Rules\\TwoWayBindingRule';\nexport * from './Utils/AngularHelpers';\n````\n\nThen `dts-bundle` processes this file. When finish the temporally file is deleted.\n\n### Module folders\nNPM introduced support for in-package typings,\nit is done by adding typings key into package.json file, which should refer to the\ntypings file.\nwhen this is the case, the d.ts file is threated as module folder, and declare module\nis not allowed.\n\n* `outputAsModuleFolder`. When using this option output d.ts will be compatible with module folder. which means, no declare module are used,\nand all internal references are removed as they are merged into the output d.ts.\n\n### Files not found.\n\nExperimental - Test needed -\n\n`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, \nwhen 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 \nresult 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 \nthe bundle then you have two options to control these cases:\n\n* `emitOnIncludedFileNotFound`. When there are files not found and these file should be included in the bundle, \n`dts-bundle` writes the output file if `emitOnIncludedFileNotFound` is true. This allow you to have external file \ndefinitions that you will load by other way in your final project.\n* `emitOnNoIncludedFileNotFound`. When there are files not found and these file shouldn't be included in the bundle, \n`dts-bundle` writes the output file if `emitOnNoIncludedFileNotFound` is true. This allow you don't to include external \ntypings in your temporally output compile path.\n\n## Return value\n\nExperimental - Test needed -\n\n`bundle` function return an object that implement this interface:\n\n```` typescript\nexport interface BundleResult {\n    // a map with parse result per each process module.\n    fileMap: { [moduleName: string]: Result; };\n    // list of files not found that should be included in the bundle.\n    includeFilesNotFound: string[];\n    // list of files not found that shouldn`t be no included in the bundle.\n    noIncludeFilesNotFound: string[];\n    // true if dts-bunlde wrote the result, false otherwise.\n    emitted?: boolean;\n    // original options passed to the function. \n    options: Options;\n}\n````\n\nYou can use the return value to determine if continue your gulp or grunt task or stop and emit an error.\n\n# Command line\n\nYou can use `dts-bundle` from command line, its allow you use it from npm scripts [ see #13 ](https://github.com/TypeStrong/dts-bundle/issues/13).\nYou have to install it using -g:\n\n````\nnpm install dts-bundle -g\n````\n\nYou can use the following options:\n\n````\nUsage: dts-bundle [options]\n\nOptions:\n\n  -h, --help                      output usage information\n  -V, --version                   output the version number\n  --configJson \u003cvalue\u003e            path to json config file. Load it first and override options with additional parameters\n  --name \u003cvalue\u003e                  name of module likein package.json *required\n  --main \u003cvalue\u003e                  path to entry-point (see documentation) *required\n  --baseDir [value]               base directory to be used for discovering type declarations\n  --out [value]                   path of output file. Is relative from baseDir but you can use absolute paths.\n  --externals                     include typings outside of the \"baseDir\" (i.e. like node.d.ts)\n  --referenceExternals            reference external modules as \u003creference path=\"...\" /\u003e tags\n  --removeSource                  delete all source typings (i.e. \"\u003cbaseDir\u003e/**/*.d.ts\")\n  --newline [style]               newline style to use in output file =\u003e unix|windows|currentOsDefault\n  --prefix [value]                prefix for rewriting module names\n  --verbose                       enable verbose mode, prints detailed info about all references and includes/excludes\n  --emitOnIncludedFileNotFound    emit although included files not found. See readme \"Files not found\" section.\n  --emitOnNoIncludedFileNotFound  emit although no included files not found. See readme \"Files not found\" section.\n  --outputAsModuleFolder          output as module folder format (no declare module) . See readme \"Module folders\" section.\n  --headerPath [value]            path to file that contains the header\n  --headerText [value]            text of the header. Doesn't work with headerPath.\n````\n\nFor example: \n````\ndts-bundle --name cool-project --main build/output/index.d.ts\n````\nYou can load config from a json file:\n```` json\n// dts-bundle.json file\n{\n    \"name\": \"cool-project\",\n    \"main\": \"tmp/out/index.d.ts\"\n}\n````\nRun this way:\n````\ndts-bundle --configJson dts-bundle.json\n````\nAnd can override properties:\n````\ndts-bundle --configJson dts-bundle.json --name coolest\n````\nEmitting `tmp/out/cooles.d.ts`.\n\n\n## Todo\n\n- add feature to create a DefinitelyTyped header (using `definition-header` package)\n- add feature to auto-update package.json/bower.json with the definition link\n- find time to implement a parser based solution\n- run IO asyncronous\n\n\n# History\n\n* 0.4.x Several features.\n  * CLI command\n  * Support not found file (`emitOnIncludedFileNotFound` and `emitOnNoIncludedFileNotFound`)\n  * Output relative to current path using \"~/\"\n  * referenceExternals option\n  * All files feature using `**/*.d.ts` on `main` option\n  * Return a object with the result\n  * Add Header using `headerPath` \n* 0.3.x - Support es6 module syntax \u0026 rewrite by TypeScript\n* 0.2.x - Fixed bugs \u0026 added many options (thanks @poelstra)\n* 0.1.x - First release\n\n## Key People\n\n* [Javier Ros (tolemaC)](http://github.com/tolemac) : current lead\n* [Bart van der Schoor](https://github.com/Bartvds) : original creator\n\n## Contributions\n\nThey are very welcome. Beware this module is a quick hack-job so good luck!\n\n* Martin Poelstra (@poelstra): Exclude 'external' typings, optional debug output, improved configurability.\n\n## License\n\nLicensed under the MIT license.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTypeStrong%2Fdts-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTypeStrong%2Fdts-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTypeStrong%2Fdts-bundle/lists"}