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