npm-dts
by Vytenis Urbonavičius
This utility generates single index.d.ts file for whole NPM package.
It allows creating bundled NPM library packages without TypeScript sources and yet still keeping code suggestions wherever these libraries are imported.
TypeScript picks up index.d.ts automatically.
---
Installation
Local: ``` npm install --save-dev npm-dts ``` Global: ``` npm install -g npm-dts ``` ---CLI Usage
Please make sure that target project has "typescript" installed in nodemodules. To see full CLI help - run without arguments: ``` npm-dts ``` Typical usage (using global install): ``` cd /your/project npm-dts generate ```Supported options
``` npm-dts options generate ``` | Option | Alias | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |--entry file
| -e file
| Allows changing main src file from index.ts to something else. It can also be declared as a path, relative to rootDir of TSC. Note that if rootDir is not specified in tsconfig.json and all TS source code is under some sub-directory such as "src" - TSC might auto-magically set rootDir to "src". |
| --force
| -f
| Ignores non-critical errors and attempts to at least partially generate typings (disabled by default). |
| --help
| -h
| Output usage information. |
| --logLevel level
| -L level
| Log level (error, warn, info, verbose, debug) (defaults to "info"). |
| --output file
| -o file
| Overrides recommended output target to a custom one (defaults to "index.d.ts"). |
| --root path
| -r path
| NPM package directory containing package.json (defaults to current working directory). |
| --tmp path
| -t path
| Directory for storing temporary information (defaults to OS-specific temporary directory). Note that tool completely deletes this folder once finished. |
| --tsc options
| -c options
| Passed through additional TSC options (defaults to ""). Note that they are not validated or checked for suitability. When passing through CLI it is recommended to surround arguments in quotes and start with a space (work-around for a bug in argument parsing dependency of npm-dts). |
| --version
| -v
| Output the version number. |
Integration using WebPack
You would want to use "npm-dts-webpack-plugin" package instead.Integration into NPM scripts
Example of how you could run generation of index.d.ts automatically before every publish. ``` { // ...... "scripts": {"prepublishOnly": "npm run dts && ......",
"dts": "./node_modules/.bin/npm-dts generate"
}
// ......
}
```
Another possible option would be to execute "npm run dts" as part of bundling task.
Integration into custom solution
This approach can be used for integration with tools such as WebPack. Simple usage with all default values: ```typescript import {Generator} from 'npm-dts' new Generator({}).generate() ``` Advanced usage example with some arguments overridden: ```typescript import as path from 'path' import {Generator} from 'npm-dts' new Generator({ entry: 'main.ts', root: path.resolve(process.cwd(), 'project'), tmp: path.resolve(process.cwd(), 'cache/tmp'), tsc: '--extendedDiagnostics', }).generate() ``` Above examples were in TypeScript. Same in plain JavaScript would look like this: ```javascript const path = require('path') new (require('npm-dts').Generator)({ entry: 'main.ts', root: path.resolve(process.cwd(), 'project'), tmp: path.resolve(process.cwd(), 'cache/tmp'), tsc: '--extendedDiagnostics', }).generate() ```Additional arguments
Constructor of generator also supports two more boolean flags as optional arguments:- Enable log
- Throw exception on error