I’ve researched in the TypeScript docs and elsewhere and I haven’t found a good answer to help me understand the difference or why one works over the other.

In our project, we made a @types folder within the root of the project that holds a few *.d.ts files with types we created or extended. We also have a src and test folder in the root.

My teammate suggested using the typeRoots option should allow a root-level types folder to be used within a project:

{
  "compilerOptions": {
    "target": "es2020",
    "module": "CommonJS",
    // other options
    "skipLibCheck": false,
    "typeRoots": ["node_modules/@types", "./@types"],
  },
  "include": [
    "src/**/*.ts", "test/**/*.ts",
  ]
}

However, I found that adding this into the include option instead actually works, whereas the first example results in build errors because the types cannot be located:

{
  "compilerOptions": {
    "target": "es2020",
    "module": "CommonJS",
    // other options
    "skipLibCheck": false,
  },
  "include": [
    "@types/**/*.ts", "src/**/*.ts", "test/**/*.ts",
  ]
}

Does anyone understand why this is the case? The definitions in the documentation, to me, seemed to be missing this to help me better understand.