あるあるな要件

VSCodeをコードエディタとして利用したい
Typescriptで開発したい
Typescript -> Javascript(CommonJS or ECMAScript)へのトランスパイルをしたい
jestやmocha等、自動テストフレームワークを導入したい
相対パス参照地獄を解消する為に、tsconfig に paths を設定したい

tsconfig.json

"compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    },
  }
}

./src/*以外にも./test/*や./__test__/*等、スクリプトコードの用途によってディレクトリを分けたい
ただし./src/*配下のみをトランスパイルの対象としたい
etc...

あるあるのエラー

トランスパイルは通るけれども、VSCodeの問題コンソールにはエラーが出まくっててすごい気持ち悪い

VSCode : 問題タブ

入力ファイルを上書きすることになるため、ファイル '<module file name>' を書き込めません。ts

VSCode : 問題タブ

モジュール '@/<module path>' またはそれに対応する型宣言が見つかりません。ts(2307)

結論

tsconfig.jsonを２種類用意する

VSCode用の'tsconfig.json'
トランスパイル用のtsconfig.build.json

※VSCodeはプロジェクトのルートディレクトリにあるtsconfig.jsonしか参照できない

構成例

ビルドツール：tsc + tsc-alias
テストランナー：ts-mocha + mocha + tsconfig-path
アサーションライブラリ：chai

ディレクトリ構成

root

`./tsconfig.json`

./tsconfig.json

{
  "compilerOptions": {
    // ...中略...

    // 任意の相対パス
    "baseUrl": ".",

    // 任意の相対パス
    "paths": {
      "@/*": [
        "./src/*"
      ]
    },

    // 「入力ファイルを～」エラー回避に必須。
    "outDir": "./.build"
  },

  // ～対応する型宣言が～」エラー回避の為に必須
  "include": [
    "./src/**/*",
    "./test/**/*"
  ],
}

./tsconfig.build.json

./tsconfig.build.json

{
  // 基本設定は、tsconfig.json から継承
  "extends": [
    "./tsconfig.json"
  ],

  "compilerOptions": {
    // imoprt スコープの範囲を src 配下に狭める
    "rootDir": "./src",
  },

  // 必須
  // トランスパイルの範囲を ./src/ 配下のみに指定
  "include": [
    "./src/**/*",
  ],

  // 必須
  // トランスパイルから除外する
  // node_modules 等も必須
  "exclude": [
    "./test/**/*",
    "node_modules",
    "**/node_modules/"
  ]
}

./package.json

./package.json

{
  // ...中略...
  "main": ".build/index.js",

  "scripts": {
    "prebuild": "rm -rf .build",

    // -p オプションで、ビルド用のtsconfigを指定する
    "build": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",

    // -p オプションで、VSCode用のtsconfigを指定する
    "test": "ts-mocha test/**/*.spec.ts --paths -p ./tsconfig.json -R spec"
  },

  // 以下は参考用
  "devDependencies": {
    "@types/chai": "^4.3.5",
    "@types/expect": "^24.3.0",
    "@types/mocha": "^10.0.1",
    "chai": "^4.3.7",
    "mocha": "^10.2.0",
    "ts-mocha": "^10.0.0",
    "ts-node": "^10.9.1",
    "tsc-alias": "^1.8.7",
    "tsconfig-paths": "^4.2.0",
    "typescript": "^5.1.6"
  }
}

※そのうちまとめなおすかも。。。
※StackOverflowに「tsconfig.app.json作りぃ」「何に使うねん。」って会話が残ってて、頷き過ぎて首もげそうだった。。。

了