docs: add comments for nearly all tsconfig options in use

agilgur5 · agilgur5 · commit 10a613749b9f · 2020-09-17T19:02:24.000-04:00
- since we can use comments in tsconfig.json, add them to give simple,
  one-liner explanations as to what each setting does
- also add a link to the TSConfig Reference for further details
- and specify which options are recommended as true by TS but not on by
  default for backwards compat or other reasons

- a few leftover that I still need to think about
diff --git a/templates/basic/tsconfig.json b/templates/basic/tsconfig.json
@@ -1,22 +1,34 @@
 {
+  // see https://www.typescriptlang.org/tsconfig to better understand tsconfigs
   "include": ["src", "types"],
   "compilerOptions": {
     "module": "esnext",
     "lib": ["dom", "esnext"],
     "importHelpers": true,
+    // output .d.ts declaration files for consumers
     "declaration": true,
+    // output .js.map sourcemap files for consumers
     "sourceMap": true,
+    // match output dir to input dir. e.g. dist/index instead of dist/src/index
     "rootDir": "./src",
+    // stricter type-checking for stronger correctness. Recommended by TS
     "strict": true,
+    // linter checks for common issues
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
     "noFallthroughCasesInSwitch": true,
+    // use Node's module resolution algorithm, instead of the legacy TS one
     "moduleResolution": "node",
+    // transpile JSX to React.createElement
     "jsx": "react",
+    // interop between ESM and CJS modules. Recommended by TS
     "esModuleInterop": true,
+    // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS
     "skipLibCheck": true,
+    // error out if import and file system have a casing mismatch. Recommended by TS
     "forceConsistentCasingInFileNames": true,
+    // `tsdx build` ignores this option, but it is commonly used when type-checking separately with `tsc`
     "noEmit": true,
   }
 }
diff --git a/templates/react-with-storybook/tsconfig.json b/templates/react-with-storybook/tsconfig.json
@@ -1,22 +1,34 @@
 {
+  // see https://www.typescriptlang.org/tsconfig to better understand tsconfigs
   "include": ["src", "types"],
   "compilerOptions": {
     "module": "esnext",
     "lib": ["dom", "esnext"],
     "importHelpers": true,
+    // output .d.ts declaration files for consumers
     "declaration": true,
+    // output .js.map sourcemap files for consumers
     "sourceMap": true,
+    // match output dir to input dir. e.g. dist/index instead of dist/src/index
     "rootDir": "./src",
+    // stricter type-checking for stronger correctness. Recommended by TS
     "strict": true,
+    // linter checks for common issues
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
     "noFallthroughCasesInSwitch": true,
+    // use Node's module resolution algorithm, instead of the legacy TS one
     "moduleResolution": "node",
+    // transpile JSX to React.createElement
     "jsx": "react",
+    // interop between ESM and CJS modules. Recommended by TS
     "esModuleInterop": true,
+    // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS
     "skipLibCheck": true,
+    // error out if import and file system have a casing mismatch. Recommended by TS
     "forceConsistentCasingInFileNames": true,
+    // `tsdx build` ignores this option, but it is commonly used when type-checking separately with `tsc`
     "noEmit": true,
   }
 }
diff --git a/templates/react/tsconfig.json b/templates/react/tsconfig.json
@@ -1,22 +1,34 @@
 {
+  // see https://www.typescriptlang.org/tsconfig to better understand tsconfigs
   "include": ["src", "types"],
   "compilerOptions": {
     "module": "esnext",
     "lib": ["dom", "esnext"],
     "importHelpers": true,
+    // output .d.ts declaration files for consumers
     "declaration": true,
+    // output .js.map sourcemap files for consumers
     "sourceMap": true,
+    // match output dir to input dir. e.g. dist/index instead of dist/src/index
     "rootDir": "./src",
+    // stricter type-checking for stronger correctness. Recommended by TS
     "strict": true,
+    // linter checks for common issues
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
     "noFallthroughCasesInSwitch": true,
+    // use Node's module resolution algorithm, instead of the legacy TS one
     "moduleResolution": "node",
+    // transpile JSX to React.createElement
     "jsx": "react",
+    // interop between ESM and CJS modules. Recommended by TS
     "esModuleInterop": true,
+    // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS
     "skipLibCheck": true,
+    // error out if import and file system have a casing mismatch. Recommended by TS
     "forceConsistentCasingInFileNames": true,
+    // `tsdx build` ignores this option, but it is commonly used when type-checking separately with `tsc`
     "noEmit": true,
   }
 }
