Create a tsconfig.json

Without a configuration file, every tsc invocation needs the same flags repeated on the command line, and your editor has no way to know which rules apply. A tsconfig.json fixes both problems: it marks a TypeScript project root and records the compiler settings once.

Create a starting configuration:

npx tsc --init

This generates a tsconfig.json full of commented-out options. It works, but I prefer starting from a small explicit file instead:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  },
  "include": ["src/**/*.ts"]
}

Each part has a job. The include and exclude patterns choose the source files, while compilerOptions controls checking and output. target decides which JavaScript syntax the compiler may emit. module and moduleResolution decide how imports are written and resolved.

The correct module settings depend on the runtime and build tool. NodeNext is right for modern Node.js. A browser bundle built with Vite typically wants "module": "ESNext" with "moduleResolution": "bundler". Do not copy them blindly between a Node.js app and a browser bundle.

Verify the project boundary

Run the project compiler without file arguments:

npx tsc --noEmit

When tsc runs with no file arguments, it walks up from the current directory, finds tsconfig.json, and checks exactly the files matched by include. No output means every file passed.

Passing individual files can bypass the project configuration you intended to test. npx tsc src/index.ts ignores your tsconfig.json entirely and falls back to default compiler options, so it can pass while the real project check fails.

A common failure mode

If the checker seems to ignore a file, it is usually outside the include patterns. Confirm what the project actually contains:

npx tsc --noEmit --listFiles

The output lists every file in the compilation, including library declaration files. If your file is missing from the list, fix the glob rather than the file.

Keep tsconfig.json in version control so editors, local checks, and continuous integration agree.

Exercise: create one .ts file inside src and another outside it. Run npx tsc --noEmit --listFiles and inspect which files belong to the project.