dumble

Dumble is a zero-configuration bundler for your TypeScript project.

It automatically reads tsconfig.json and package.json to determine what files to bundle, which is the desired format, where to output the files, and more.

Inspired by pkgroll.

Quick Setup

1. Install:

npm install --save-dev dumble

2. Add a build script:

{
    "scripts": {
        "build": "tsc -b && dumble"
    }
}

Note: dumble is intended to be used together with tsc (TypeScript compiler). tsc is useful for type checking and generating .d.ts files, while dumble is used for bundling and tree-shaking .js files.

3. Start building:

npm run build

Configuration

For most scenarios, you don't need to configure anything. Below are some properties you can set in tsconfig.json and package.json to customize the build process.

// tsconfig.json
{
    "compilerOptions": {
        // the input and output directories
        "rootDir": "src",
        "outDir": "lib",

        // if you want .d.ts files,
        // set "declaration" and "emitDeclarationOnly" to true
        "declaration": true,
        "emitDeclarationOnly": true,

        // if you don't want .d.ts files,
        // simply set "noEmit" to true
        "noEmit": true,

        // target and sourcemaps are also respected
        "target": "esnext",
        "sourceMap": true,
    },
}

// package.json
{
    "name": "my-package",

    // module system (https://nodejs.org/api/packages.html#type)
    "type": "module",

    // output files
    "main": "./dist/index.cjs",
    "module": "./dist/index.mjs",
    "types": "./dist/index.d.cts",

    // export map (https://nodejs.org/api/packages.html#exports)
    "exports": {
        "require": {
            "types": "./dist/index.d.cts",
            "default": "./dist/index.cjs"
        },
        "import": {
            "types": "./dist/index.d.mts",
            "default": "./dist/index.mjs"
        }
    },

    // bin files will be compiled to be executable with the Node.js hashbang
    "bin": "./dist/cli.js",
}

Basic Usage

Entry Points and Exports

| package.json property | Output Format | | --- | --- | | main | auto-detected | | module | esmodule | | types | declaration | | exports.* | auto-detected | | exports..require | commonjs | | exports..import | esmodule | | bin | auto-detected |

Auto-detection is based on the extension and the type field in package.json:

| Extension | Type | | --- | --- | | .cjs | commonjs | | .mjs | esmodule | | .js | esmodule if type is "module", commonjs otherwise |

Dependency bundling

Packages to externalize are detected by reading dependency types in package.json:

| Dependency Type | Behavior | | --- | --- | | dependencies | external | | peerDependencies | external | | optionalDependencies | external | | devDependencies | bundle | | not listed | error |

More Options

Although dumble tries it best to infer the configuration you need, there are still some cases where you may want to manually customize your build. Basically, all the additional options are consistent with the esbuild CLI.

Target

target is automatically detected from tsconfig.json. If you want to override it, you can set --target option.

dumble --target=node14

Source Maps

sourceMap is automatically detected from tsconfig.json, but it only supports a boolean value. If you want to further customize it, you can set --sourcemap option.

dumble --sourcemap=inline

Minification

Dumble does not minify your code by default. If you want to minify your code, you can set --minify option.

dumble --minify

Credits

pkgroll is a similar project that inspired this one. It actually provides more features, such as

• --watch
• .d.ts bundling
• rollup-based minification (which is slightly smaller than esbuild)

If you find dumble not satisfying your needs, consider using pkgroll instead (better yet, open an issue or pull request to improve dumble).

Compared to pkgroll, dumble is simpler and more focused on zero-configuration. Also, dumble can be easily integrated into a monorepo with multiple packages, and can be further customized with esbuild options.