dtsbuild

Appearance

Build Options ​

Options for the build() API.

ts
import { build } from '@dtsbuild/core'

await build({
  entryPoints: ['src/index.ts'],
  // ...
})

The build() API can also be called from the CLI, e.g. dtsbuild src/index.d.ts. Most options below can be passed as CLI options like --outDir dist, and any special CLI behaviors are noted below.

entryPoints ​

  • Type: string[] | Record<string, string>
  • CLI: Passed directly, e.g. dtsbuild src/index.d.ts or dtsbuild main=src/index.ts (for object form)

The entry points to build. It can be an array of input paths, or an object of names to input paths. With the object form, the name will be used as the [name] placeholder in the entryNames option. (Relative paths are resolved from the cwd option.)

outDir ​

  • Type: string
  • Default: "dist"

The directory to output files to. (Relative path is resolved from the cwd option.)

emptyOutDir ​

  • Type: boolean
  • Default: false

Whether to empty the outDir before writing the output files. This will remove all files recursively in the directory even if it wasn't generated by dtsbuild before.

outBase ​

  • Type: string

The base directory among each input paths. By default, it will search for the deepest common directory among the input paths. For example, if you have input paths like:

  • /project/src/entry/index.ts
  • /project/src/entry/utils.ts

It will infer the base directory as /project/src/entry. You can use this option to change the base to, for example, /project/src to change how the files are outputted. The relative path from outBase to each input paths will be used as the [dir] placeholder in the entryNames options. (Relative path is resolved from the cwd option.)

outExtension ​

  • Type: string
  • Default: "d.ts"

The extension to use for the output files. You can set this as "d.mts" or "d.cts" if you need to output explicit ESM or CJS formats respectively.

entryNames ​

  • Type: string
  • Default: "[dir]/[name].[ext]"

The output file name for each entry points.

  • [dir]: The relative directory resolved from outBase
  • [name]: The base name of the entry point
  • [ext]: The outExtension

chunkNames ​

  • Type: string
  • Default: "[name]-[count].[ext]"

The output file name for each chunk.

  • [name]: The chunk base name (currently always chunk)
  • [count]: The current chunk count (1-based)
  • [ext]: The outExtension

external ​

  • Type: string[]
  • CLI: Multiple values can be passed as comma-separated, e.g. --external "foo,@bar/*"
  • Default: Dependency imports (see below)

An array of glob patterns to externalize in the build (the import paths are left as-is and not bundled).

The patterns are matched against pre-resolved ids and post-resolved ids (if the pre-resolved id is no externaled on the first pass), e.g. "my-lib" and "/project/node_modules/my-lib/index.d.ts". Negated patterns are supported and patterns are matched in the order they're defined.

By default, dependency imports such as foo, @foo/bar, foo/nested, node:fs, etc are externalized, unless the dependency is found as a dev dependency in packageJson. If an alias such as @src/foo.js is setup that looks like a dependency import, you would need to manually exclude it from externalizing.

Example:

To exclude certain paths from externalizing, set ["!foo", "!@src/**", ...] for example, which causes the build to externalize all dependencies except foo and @src/** aliases.

If the default dev dependencies behavior isn't desired, you can set packageJson to false to disable it. If the entire default behavior isn't desired, you can reset it with ["!**/**", ...] and manually specify the dependencies to externalize.

packageJson ​

  • Type: boolean | string
  • Default: true, "package.json" in the cwd

The path to a package.json file. Its devDependencies field will be used automatically for external so that they are bundled by default (not externaled). Internally, this prepends ["!dev-dep-1", "!dev-dep-2", ...] to the external option for example.

tsconfig ​

  • Type: string
  • Default: tsconfig.json in cwd

The path to a tsconfig.json file.

Minor TypeScript behavior deviation

Multiple tsconfig files (e.g. nested tsconfig.json) are not supported unlike in normal TypeScript as it would require every file to search for its corresponding tsconfig, which is a big performance hit to avoid for now. This may be revisited in the future.

ambientFiles ​

  • Type: string[]

Path to ambient files where each declare module "..." are scanned and used in the build. For example, if you have declare module "*.svg" {... } setup, the build will be able to bundle the .svg files with the specified types.

Minor TypeScript behavior deviation

In normal TypeScript, ambient files are automatically picked up from tsconfig.json include so manual configuration technically isn't necessary. However, this would require analyzing every included file for ambient types, which can cause a big performance hit.

By default, dtsbuild only analyzes files that are reached by the entry points (including on-the-fly treeshaking if types referenced imported types were never exported publicly).

cwd ​

  • Type: string
  • Default: process.cwd()

The current working directory. This will be used to resolve all relative paths in the config.