# dts-generator

> .d.ts generator. Generates a single d.ts bundle containing external modules from TypeScript files.

Latest version **3.0.0** (published 2019-01-08) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install dts-generator
pnpm add dts-generator
yarn add dts-generator
bun add dts-generator
```

Provides the command `dts-generator`.

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2019-01-08 |
| First published | 2015-04-08 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | separate (@types/dts-generator) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 35.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 514 |
| Maintainers | sitepen |

## Links

- npm: https://www.npmjs.com/package/dts-generator
- Repository: https://github.com/SitePen/dts-generator
- Homepage: https://github.com/SitePen/dts-generator#readme
- Issues: https://github.com/SitePen/dts-generator/issues
- npm.io page: https://npm.io/package/dts-generator

## Dependencies (2)

- [glob](https://npm.io/package/glob.md) ^7.1.3
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1

## Recent versions

- 3.0.0 (latest) — 2019-01-08
- 2.1.0 — 2017-02-05
- 2.0.0 — 2016-10-11
- 1.7.0 — 2016-03-01
- 1.6.3 — 2015-12-01
- 1.6.2 — 2015-11-03
- 1.6.1 — 2015-11-03
- 1.6.0 — 2015-11-03
- 1.6.0-pre.1 — 2015-10-14
- 1.5.0 — 2015-06-17
- 1.4.2 — 2015-06-17
- 1.4.1 — 2015-04-21
- 1.4.0 — 2015-04-21
- 1.3.1 — 2015-04-10
- 1.3.0 — 2015-04-08

## README

.d.ts generator
===============

[![Build Status](https://travis-ci.org/SitePen/dts-generator.svg?branch=master)](https://travis-ci.org/SitePen/dts-generator)

Generates a single `.d.ts` bundle containing external module declarations exported from TypeScript module files.

## What does this mean?

If you have a project with lots of individual TypeScript files that are designed to be consumed as external modules,
the TypeScript compiler doesn’t allow you to actually create a single bundle out of them. This package leverages the
TypeScript language services in TypeScript 1.4+ to generate a single `.d.ts` file containing multiple
`declare module 'foo'` declarations. This allows you to distribute a single `.d.ts` file along with your compiled
JavaScript that users can simply reference from the TypeScript compiler using a `/// <reference path />` comment.

`.d.ts` generator will also correctly merge non-external-module files, and any already-existing `.d.ts` files.

## Usage

1. `npm install dts-generator`

2. Generate your `d.ts` bundle:

   Programmatically:

```js
require('dts-generator').default({
		name: 'package-name',
		project: '/path/to/package-directory',
		out: 'package-name.d.ts'
});
```

   Command-line:

```bash
dts-generator --name package-name --project /path/to/package-directory --out package-name.d.ts
```

   Grunt:

```js
module.exports = function (grunt) {
	grunt.loadNpmTasks('dts-generator');
	grunt.initConfig({
		dtsGenerator: {
			options: {
				name: 'package-name',
				project: '/path/to/package-directory',
				out: 'package-name.d.ts'
			},
			default: {
				src: [ '/path/to/package-directory/**/*.ts' ]
			}
		}
	});
};
```

3. Reference your generated d.ts bundle from somewhere in your consumer module and import away!:

```ts
/// <reference path="typings/package-name.d.ts" />

import Foo = require('package-name/Foo');

// ...
```

## Options

* `baseDir?: string`: The base directory for the package being bundled. Any dependencies discovered outside this
  directory will be excluded from the bundle.  *Note* this is no longer the preferred way to configure `dts-generator`, 
  it automatically gets its value from compiler option `rootDir` if specified in `tsconfig.json`, otherwise it gets value from `project`. Please see option `project`.
* `exclude?: string[]`: A list of glob patterns, relative to `baseDir`, that should be excluded from the bundle. Use
  the `--exclude` flag one or more times on the command-line. Defaults to `[ "node_modules/**/*.d.ts" ]`.
* `externs?: string[]`: A list of external module reference paths that should be inserted as reference comments. Use
  the `--extern` flag one or more times on the command-line.
* `types?: string[]`: A list of external @types package dependencies that should be inserted as reference comments. Use
  the `--types` flag one or more times on the command-line.
* `files: string[]`: A list of files from the baseDir to bundle.
* `eol?: string`: The end-of-line character that should be used when outputting code. Defaults to `os.EOL`.
* `indent?: string`: The character(s) that should be used to indent the declarations in the output. Defaults to `\t`.
* `main?: string`: The module ID that should be used as the exported value of the package’s “main” module.
* `moduleResolution?: ts.ModuleResolutionKind`: The type of module resolution to use when generating the bundle.
* `name: string`: The name of the package. Used to determine the correct exported package name for modules.
* `out: string`: The filename where the generated bundle will be created.
* `project?: string`: The base directory for the project being bundled.  It is assumed that this directory contains a `tsconfig.json` which will be parsed to determine the files that should be bundled as well as other configuration information like `target`
* `target?: ts.ScriptTarget`: The target environment for generated code. Defaults to `ts.ScriptTarget.Latest`.
* `resolveModuleId: (params: ResolveModuleIdParams) => string`: An optional callback provided by the invoker to customize the declared module ids the output d.ts files. For details see [resolving module ids](docs/resolving-module-ids.md).
* `resolveModuleImport: (params: ResolveModuleImportParams) => string`: An optional callback provided by the invoker to customize the imported module ids in the output d.ts files. For details see [resolving module ids](docs/resolving-module-ids.md).

## Known issues

* Output bundle code formatting is not perfect yet

## Thanks

[@fdecampredon](https://github.com/fdecampredon) for the idea to dump output from the compiler emitter back into the compiler parser instead of trying to
figure out how to influence the code emitter.

## Licensing

© 2015-2019 SitePen, Inc. New BSD License.

---
_Source: https://npm.io/package/dts-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._