tsconfig.json Basics

Running tsc on individual files works for quick experiments, but a real project needs a configuration file. tsconfig.json tells the compiler where your source files are, where to put the compiled output, and which rules to enforce.

Create tsconfig.json

Run this command in your project root:

npx tsc --init

This generates a tsconfig.json with every available option commented out, and a handful of sensible defaults enabled. For AceIt you will replace it with a minimal configuration that only sets what the project actually needs.

The AceIt tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "strict": true,
    "lib": ["ES2020", "DOM"],
    "noEmitOnError": true
  },
  "include": ["./*.ts"],
  "exclude": ["dist"]
}

Each option has a specific job.

compilerOptions

target — the JavaScript version the compiler outputs. "ES2020" is widely supported and keeps modern syntax like ??, ?., and async/await intact in the output without polyfills.

module — the module system used in the output files. "ES2020" produces ES module syntax (import / export) that browsers understand natively.

moduleResolution — how the compiler resolves import paths. "bundler" is the modern setting for projects using ES modules without a bundler — it allows you to import with .js extensions in your TypeScript files (which is what the browser needs), while the compiler resolves those to .ts source files during the build.

outDir — where compiled .js files are written. "./dist" keeps output separate from source. The file types.ts compiles to dist/types.js, main.ts to dist/main.js, and so on.

strict — enables the full suite of strict type-checking rules with a single flag. This includes:

• strictNullChecks — null and undefined are not assignable to other types without explicit handling
• noImplicitAny — variables without an inferable type must be annotated explicitly
• strictFunctionTypes — stricter checking on function parameter types

Always use strict: true. Turning it off trades short-term convenience for long-term errors that TypeScript was specifically designed to prevent.

lib — which built-in type definitions are available. "ES2020" includes modern JavaScript APIs. "DOM" includes browser APIs like document, window, fetch, and localStorage. Without "DOM", TypeScript does not know those APIs exist.

noEmitOnError — prevents the compiler from writing output files when there are type errors. Without this, dist/ can contain compiled JavaScript that came from broken source — confusing and dangerous.

include and exclude

include — which files to compile. ["./*.ts"] compiles every .ts file in the project root (the five AceIt source files).

exclude — which files or folders to ignore. ["dist"] prevents the compiler from trying to compile its own output.

Running tsc with tsconfig.json

Once tsconfig.json exists, running tsc with no arguments reads the configuration and compiles accordingly:

npx tsc

All five source files compile to dist/ in one step. Run npm run build if you added the script in Lesson 02.

.gitignore

The dist/ folder is generated output — it should not be committed to version control. Add it to .gitignore:

dist/
node_modules/

Anyone who clones the project runs npm install and npm run build to regenerate it.

Exercise

1. Delete the tsconfig.json generated by npx tsc --init (if you ran it).
2. Create a fresh tsconfig.json with the AceIt configuration above.
3. Run npx tsc from the project root. Confirm that dist/ is created and contains .js files for each .ts source file.
4. Introduce a type error in one of your .ts files. Run npx tsc again and confirm that the compiler reports the error and produces no output (because of noEmitOnError).
5. Add dist/ and node_modules/ to .gitignore.

Recap

• tsconfig.json configures the compiler — source files, output location, and type-checking rules.
• target and module control the JavaScript version and module syntax in the output.
• outDir separates compiled output from source files.
• strict: true enables the full suite of type-checking rules — always use it.
• lib: ["ES2020", "DOM"] makes browser APIs available to the type checker.
• noEmitOnError prevents broken output — compiled files only appear when source is type-correct.
• dist/ and node_modules/ belong in .gitignore.