1 | .d.ts generator
|
2 | ===============
|
3 |
|
4 | [![Build Status](https://travis-ci.org/SitePen/dts-generator.svg?branch=master)](https://travis-ci.org/SitePen/dts-generator)
|
5 |
|
6 | Generates a single `.d.ts` bundle containing external module declarations exported from TypeScript module files.
|
7 |
|
8 | ## What does this mean?
|
9 |
|
10 | If you have a project with lots of individual TypeScript files that are designed to be consumed as external modules,
|
11 | the TypeScript compiler doesn’t allow you to actually create a single bundle out of them. This package leverages the
|
12 | TypeScript language services in TypeScript 1.4+ to generate a single `.d.ts` file containing multiple
|
13 | `declare module 'foo'` declarations. This allows you to distribute a single `.d.ts` file along with your compiled
|
14 | JavaScript that users can simply reference from the TypeScript compiler using a `/// <reference path />` comment.
|
15 |
|
16 | `.d.ts` generator will also correctly merge non-external-module files, and any already-existing `.d.ts` files.
|
17 |
|
18 | ## Usage
|
19 |
|
20 | 1. `npm install dts-generator`
|
21 |
|
22 | 2. Generate your `d.ts` bundle:
|
23 |
|
24 | Programmatically:
|
25 |
|
26 | ```js
|
27 | require('dts-generator').default({
|
28 | name: 'package-name',
|
29 | project: '/path/to/package-directory',
|
30 | out: 'package-name.d.ts'
|
31 | });
|
32 | ```
|
33 |
|
34 | Command-line:
|
35 |
|
36 | ```bash
|
37 | dts-generator --name package-name --project /path/to/package-directory --out package-name.d.ts
|
38 | ```
|
39 |
|
40 | Grunt:
|
41 |
|
42 | ```js
|
43 | module.exports = function (grunt) {
|
44 | grunt.loadNpmTasks('dts-generator');
|
45 | grunt.initConfig({
|
46 | dtsGenerator: {
|
47 | options: {
|
48 | name: 'package-name',
|
49 | project: '/path/to/package-directory',
|
50 | out: 'package-name.d.ts'
|
51 | },
|
52 | default: {
|
53 | src: [ '/path/to/package-directory/**/*.ts' ]
|
54 | }
|
55 | }
|
56 | });
|
57 | };
|
58 | ```
|
59 |
|
60 | 3. Reference your generated d.ts bundle from somewhere in your consumer module and import away!:
|
61 |
|
62 | ```ts
|
63 | /// <reference path="typings/package-name.d.ts" />
|
64 |
|
65 | import Foo = require('package-name/Foo');
|
66 |
|
67 | // ...
|
68 | ```
|
69 |
|
70 | ## Options
|
71 |
|
72 | * `baseDir?: string`: The base directory for the package being bundled. Any dependencies discovered outside this
|
73 | directory will be excluded from the bundle. *Note* this is no longer the preferred way to configure `dts-generator`,
|
74 | it automatically gets its value from compiler option `rootDir` if specified in `tsconfig.json`, otherwise it gets value from `project`. Please see option `project`.
|
75 | * `exclude?: string[]`: A list of glob patterns, relative to `baseDir`, that should be excluded from the bundle. Use
|
76 | the `--exclude` flag one or more times on the command-line. Defaults to `[ "node_modules/**/*.d.ts" ]`.
|
77 | * `externs?: string[]`: A list of external module reference paths that should be inserted as reference comments. Use
|
78 | the `--extern` flag one or more times on the command-line.
|
79 | * `types?: string[]`: A list of external @types package dependencies that should be inserted as reference comments. Use
|
80 | the `--types` flag one or more times on the command-line.
|
81 | * `files: string[]`: A list of files from the baseDir to bundle.
|
82 | * `eol?: string`: The end-of-line character that should be used when outputting code. Defaults to `os.EOL`.
|
83 | * `indent?: string`: The character(s) that should be used to indent the declarations in the output. Defaults to `\t`.
|
84 | * `main?: string`: The module ID that should be used as the exported value of the package’s “main” module.
|
85 | * `moduleResolution?: ts.ModuleResolutionKind`: The type of module resolution to use when generating the bundle.
|
86 | * `name: string`: The name of the package. Used to determine the correct exported package name for modules.
|
87 | * `out: string`: The filename where the generated bundle will be created.
|
88 | * `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`
|
89 | * `target?: ts.ScriptTarget`: The target environment for generated code. Defaults to `ts.ScriptTarget.Latest`.
|
90 | * `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).
|
91 | * `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).
|
92 |
|
93 | ## Known issues
|
94 |
|
95 | * Output bundle code formatting is not perfect yet
|
96 |
|
97 | ## Thanks
|
98 |
|
99 | [@fdecampredon](https://github.com/fdecampredon) for the idea to dump output from the compiler emitter back into the compiler parser instead of trying to
|
100 | figure out how to influence the code emitter.
|
101 |
|
102 | ## Licensing
|
103 |
|
104 | © 2015-2019 SitePen, Inc. New BSD License.
|