Codectionary / Developer documentation / TypeScript

tsconfig.json Basics

Learn how a TypeScript project chooses files, checks types and emits JavaScript, using a small browser-script configuration whose output you can inspect.

What tsconfig.json does

A tsconfig.json file marks a TypeScript project and stores its file selection and compiler settings. Put it at the project root. Running npx tsc without source-file arguments searches for a configuration from the current directory upward; --project selects a particular configuration explicitly. Passing a source filename directly to tsc ignores tsconfig.json, so use --project for this walkthrough.

The file contains top-level fields such as include and exclude, plus compilerOptions for type checking and JavaScript output. The compiler reads source and dependencies, reports diagnostics, and may write .js files depending on the options and whether errors occurred.

Which files belong to the project?

include selects entry files using paths or patterns relative to this configuration. Here src/**/*.ts finds .ts files inside src and its subfolders. Without files or include, TypeScript has a broader default set of supported source files under the project folder.

exclude removes matches found through include, such as generated files in dist. It is not a security boundary: a file imported by an included source file can still become part of the program. rootDir does not choose input files either; it tells the compiler what source directory structure to preserve in the output. A source file that must be emitted outside rootDir causes an error.

What the compiler options mean

target chooses the JavaScript language level to emit. It does not add missing browser APIs or polyfills. module chooses the format of emitted imports and exports. This example uses None because it is one classic browser script with no imports or exports; a bundled app or Node.js project needs settings matched to its runtime and module system.

strict enables a family of stronger type checks. lib selects the type declarations available to the checker: DOM describes browser interfaces such as document, while ES2020 describes that JavaScript language level. These declarations do not install browser features at runtime. rootDir: src and outDir: dist put src/main.ts at dist/main.js. noEmitOnError prevents new JavaScript output from a failed compilation but does not delete an older dist/main.js.

Try a configuration for one browser script

The example assumes TypeScript is installed locally with npm, the source file is src/main.ts, and a normal HTML page loads dist/main.js. Create a project folder, run the installation commands below, then save this configuration as tsconfig.json. The generated defaults from npx tsc --init can differ by TypeScript version; replace them for this specific exercise.

First run --noEmit: it checks the project without writing files. Run the second command to produce dist/main.js. If a file is missing, check your current directory, the include pattern, source filename and compiler diagnostics. Do not put noEmit: true in this build configuration if you expect a .js file; a separate check command can set --noEmit temporarily.

Install TypeScript locally

npm init -y
npm install --save-dev typescript

Browser example: tsconfig.json

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

Check without output, then build

npx tsc --project tsconfig.json --noEmit
npx tsc --project tsconfig.json

Why projects use different settings

A plain browser script can use module: None as above. A browser app using imports commonly uses ES modules and may also need a development server or bundler; its HTML must load the matching emitted file. A Node.js project may use CommonJS or native ES modules depending on package.json, file extensions and the supported Node release. Frameworks often provide their own recommended tsconfig settings and build pipeline.

If a bundler produces the JavaScript, teams may set noEmit: true so tsc checks types while the bundler writes output. For a direct tsc build like this one, leave noEmit false and select an outDir. Copying options from an unrelated environment can produce files that the intended runtime cannot load.

Syntax

npx tsc --project tsconfig.json --noEmit
npx tsc --project tsconfig.json

Examples

A typed value in a browser script

Run this small TypeScript example in the documentation preview; use the full configuration above for a real project type check.

const message: string = "Configuration affects the emitted JavaScript.";
console.log(message);
  1. The annotation tells the TypeScript checker that message should be a string. The documentation preview transforms this file for the browser but does not run a full project type check.
  2. After compilation, the annotation is gone while the string and console.log remain. The preview console displays the message.
  3. In the local project, run npx tsc --project tsconfig.json --noEmit to check all selected files; run without --noEmit to write JavaScript.

Best practices

  • Choose target and module for the actual runtime and build tool.
  • Use include for source selection; rootDir only shapes output paths.
  • Check errors before using emitted files, and remember older output may remain after a failure.
  • Keep check-only and build commands distinct when noEmit is involved.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading