cts-types

A command line script for generating d.cts files from d.ts files.

Supporting esmodules and commonjs in the same Typescript library that is itself an esmodule is not straight forward. At the time of creating this library, Typescript's new module resolution strategies requires esmodule libraries that support commonjs to provide a set of types suffixed with d.cts instead of d.ts.

Without d.cts files, Typescript assumes the library only supports esmodules and throws an error when you try to require() the commonjs version of the library. For more information about this, read the Github issue about NodeNext duel package resolution.

cts-types streamlines the process of generating d.cts files. Just install it as a dev dependency and run the cts-types build command in your pipeline after generating the d.ts files. The script will not just copy and rename files, it will also update references to .d.cts and .d.cts.map in the content of a file.

Install package

# terminal
npm add cts-types --save-dev

Usage

// package.json
{
  ...
  "types": "./dist/types/cjs/index.d.cts",
  "exports": {
    "types": {
      "import": "./dist/types/esm/index.d.ts",
      "require": "./dist/types/cjs/index.d.cts"
    },
    ...
  },
  ...
  "scripts": {
    ...
    "compile:types": "tsc --project ./tsconfig.build.json && cts-types build dist/types/esm dist/types/cjs",
    ...
  }
  ...
}

// tsconfig.build.json
{
  ...
  "compilerOptions": {
    ...
    "outDir": "dist/types/esm"
    ...
  },
  ...
}

API

ctsTypes build <input> <output>

Build .d.cts type files from .d.ts files to provide types for both esm and cjs outputs.

Positionals:
  input   The directory where the .d.ts files are located, relative to the
          project root                                       [string] [required]
  output  The directory where the .d.cts files should be output, relative to the
          project root                                       [string] [required]

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]
  --verbose  Whether to output verbose logs                            [boolean]

A note on output

The output should be in the same folder as or a sibling folder of the input in order for the source maps to work correctly. The source maps include a path to the source file and that path is based on the location of the input file. This library does not currently support updating the relative path of source files in the .map files.

To get around this limitation, either do not provide an output path (and the output will be written to the input path) or have the output path leaf directory be a sibling of the input path leaf directory, i.e. input of dist/types/esm and output of dist/types/cjs.

Changelog

Check out the features, fixes and more that go into each major, minor and patch version.

License

cts-types is MIT Licensed.