perfective/ts.build

Perfective build for TypeScript projects

Perfective Build for TypeScript

The @perfective/build package provides base configurations and presets for tools like Gulp, TypeScript, Babel, etc. to reduce code duplication between projects setup.

Installation

npm install --save-dev \
    @perfective/build \
    gulp \
    typescript

Building a TypeScript project

1. Check that dev dependencies include correct versions of gulp and typescript:

   {
       "devDependencies": {
           "gulp": "^4.0.2",
           "typescript": "~5.2.2"
       }
   }

2. Setup tsconfig.json using the base tsconfig.strict.json configuration.

   {
       "extends": "@perfective/build/tsconfig.strict.json",
       "compilerOptions": {
           "rootDir": "./src"
       },
       "exclude": [
           "dist"
       ]
   }

3. Add the RequireExtension plugin to your babel.config.js. This plugin replaces .js extensions with the .cjs extensions in the NodeJS require() statements.

   const perfective = require('@perfective/build/babel');
   
   module.exports = {
       presets: [],
       plugins: [
           perfective.babelPluginRequireExtension,
       ]
   };

   Note	There is also available the babelPluginImportExtension plugin. It replaces .js extensions with .mjs, but on practice it is not needed: you only need .cjs for CommonJS and keep .js for ESM modules.

Setup Prettier

1. Add prettier as a dev dependency:

   {
       "devDependencies": {
           "prettier": "^3.1.0"
       }
   }

2. Setup .prettierrc.js:

   const perfective = require('@perfective/build/prettier');
   
   module.exports = perfective;

3. Setup .prettierignore:

   # Build
   dist
   
   # ESLint
   *.js
   *.jsx
   *.ts
   *.tsx

4. Update package.json scripts.

   {
       "scripts": {
           "lint": "npm run lint:prettier",
           "lint:prettier": "prettier --write .",
           "lint:prettier:build": "prettier --check ."
       }
   }

   Use lint:prettier during development (to fix code automatically) and lint:prettier:build to verify the build (to fail if code is not formatted).

Setup Jest

1. Add jest and related peer dependencies as dev dependencies:

   {
       "devDependencies": {
           "@types/jest": "^29.5.8",
           "jest": "^29.7.0",
           "ts-jest": "^29.1.1",
       }
   }

2. Setup jest.config.js:

   const perfective = require('@perfective/build/jest');
   
   module.exports = perfective;

3. Update package.json scripts:

   {
       "scripts": {
           "test": "jest",
           "test:build": "jest --clearCache && jest --collectCoverage"
       }
   }

   Use test for development testing and test:build to test during the build (and fail if test coverage is not sufficient).