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 \
    typescript

Building a TypeScript project

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

   {
       "devDependencies": {
           "gulp": "^5.0.1",
           "typescript": "~5.9.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 and ImportExtension plugins to your babel.config.js. RequireExtension replaces .js extensions with the .cjs extensions in require() statements. ImportExtension adds the required .mjs (or .js) extension to the import and export statements for ES modules.

   import { babelPluginImportExtension, babelPluginRequireExtension } from '@perfective/build/babel';
   
   export default {
       presets: [],
       plugins: [
           babelPluginRequireExtension,
           babelPluginImportExtension('js'), // (1)
       ]
   };

   1. Override the default extension (mjs).

Setup Prettier

1. Add prettier as a dev dependency:

   {
       "devDependencies": {
           "prettier": "^3.6.2"
       }
   }

2. Setup .prettierrc.js:

   import { config } from '@perfective/build/prettier';
   
   export default config;

3. Setup .prettierignore:

   # Build
   dist
   
   # ESLint
   *.js
   *.cjs
   *.mjs
   *.jsx
   *.ts
   *.cts
   *.mts
   *.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": "^30.0.0",
           "jest": "^30.0.5",
           "ts-jest": "^29.4.1",
       }
   }

2. Setup jest.config.js:

   import { config } from '@perfective/build/jest';
   
   export default config;

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).