@yume-chan/ts-package-builder

TypeScript NPM Package Builder (for myself)

Installation

(This package is not yet published to NPM registry, so presumably)

$ npm install --dev @yume-chan/ts-package-builder typescript

TypeScript is a peer dependency that must be installed separately (so you can use any version you want).

$ npm install tslib

The default configuration has "importHelpers": true, so tslib is required (and it is a production dependency, not dev dependency).

Config

A tsconfig.json file at package root is required for both this builder and editors.

{
    // Extends default configurations.
    "extends": "./node_modules/@yume-chan/ts-package-builder/tsconfig.base.json",

    // (Optional) Add override configurations.
    "compilerOptions": {
        // All TypeScript configurations are allowed.
        "target": "ES2016",

        // Add extra ambient types.
        // Don't forget to include "jest" unless you don't write unit tests.
        // The default is `[ "jest" ]`
        "types": [
            "w3c-web-usb",
            "jest",
            "node"
        ]
    },
    // (Optional) Specify types that's only used in tests.
    // They will be excluded in ESModule build,
    // to make sure library code doesn't accidentally use them.
    // (for example, a browser targeted libraries should not use types from `@types/node`)
    "testTypes": [
        "jest",
        "node"
    ],
    // (Optional) Add project references to improve editing experience.
    // However, because the builder is intended to be used with some monorepo manager
    // (lerna, yarn workspace, rush, etc.), and they all have good built-in support
    // for building all packages following dependency graph, it **does not** use
    // project references when building.
    "references": [
        {
            "path": "../dependency-a/tsconfig.json"
        },
        {
            "path": "../dependency-b/tsconfig.json"
        }
    ]
}

Building

$ npx build-ts-package

Or add a script to package.json

{
    "scripts": {
        "build": "build-ts-package",
    },
}

The builder compiles for both CommonJS and ESModule, also generates source maps, TypeScript declarations, and declaration maps.

Module	Output Directory	Excluded Files	Excluded Types
CommonJS	cjs	-	-
ESModule	esm	*.spec.ts	@types/jest
Declaration (d.ts)	dts	*.spec.ts	@types/jest

Example package.json:

{
    "main": "cjs/index.js",
    "module": "esm/index.js",
    "types": "dts/index.d.ts",
}

Unit test with Jest

Test file convention: put .spec.ts files inside src, alongside the source file that will be tested.

Like this:

• src
  • index.ts
  • index.spec.ts

The .spec.ts files will be compiled to CommonJS for Jest (so no ts-jest required).

Use the following jest.config.js file to find them:

module.exports = {
    testMatch: ['<rootDir>/cjs/**/*.spec.js'],
};

Publishing

Because .spec.ts files have been compiled to CommonJS, you can exclude them using .npmignore:

**/*.spec.ts
**/*.spec.js
**/*.spec.js.map