How to Generate a tsconfig.json File in TypeScript

By the end of this page, you will understand what tsconfig.json is, why TypeScript uses it, and how to generate it correctly from the command line using tsc --init. You will also learn how this file is used in real projects and what common setup mistakes to avoid.

tsconfig.json is the main configuration file for a TypeScript project. It tells the TypeScript compiler (tsc) how to compile your code.

This file can control things like:

• which files should be compiled
• which JavaScript version to output
• whether strict type checking is enabled
• where compiled files should be written
• which module system to use

When you run TypeScript in a real project, the compiler needs instructions. Instead of passing many command-line options every time, you usually store them in tsconfig.json.

To generate this file automatically, TypeScript provides a command-line flag:

tsc --init

This creates a starter tsconfig.json in the current directory.

The command tsc init does not work because init is not a positional command. It is an option flag, so it must be written with two dashes: --init.

This matters in real programming because almost every TypeScript application—frontend, backend, library, or tool—relies on a tsconfig.json file for consistent builds and editor support.

Think of tsconfig.json as the settings panel for your TypeScript project.

• Your .ts files are the raw source material.
• The TypeScript compiler is the machine that processes them.
• tsconfig.json is the instruction sheet that tells the machine how to do its job.

Without that instruction sheet, you would have to explain the settings every time by typing a long command. With tsconfig.json, you define the rules once and reuse them.

The correct command is:

tsc --init

If TypeScript is installed locally in your project, you can also run:

npx tsc --init

Example

mkdir my-app
cd my-app
npx tsc --init

This creates a tsconfig.json file in the my-app directory.

A generated file might look like this:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

What the main options mean

• target: the JavaScript version to generate
• module: the module system to use
• strict: enables stricter type checking
• esModuleInterop: improves compatibility with CommonJS modules
• skipLibCheck: skips type checking for declaration files

Compile using the config file

Once tsconfig.json exists, you can compile the project with:

tsc

TypeScript will automatically read the configuration from tsconfig.json.

Consider this sequence:

npm install --save-dev typescript
npx tsc --init
tsc

Here is what happens step by step:

1. npm install --save-dev typescript

   • Installs TypeScript in your project.
   • The tsc compiler becomes available through npx or npm scripts.

2. npx tsc --init

   • Runs the local TypeScript compiler.
   • Creates a default tsconfig.json file in the current folder.

3. tsc

   • Looks for tsconfig.json in the current directory.
   • Reads the compiler settings.
   • Compiles the TypeScript files according to those settings.

Small example project

Suppose you have this file:

const message: string = "Hello, TypeScript";
console.log(message);

If tsconfig.json is present, tsc uses its rules to compile this file into JavaScript.

If tsconfig.json is missing, you would need to pass options manually or rely on defaults.

tsconfig.json is used in many practical situations:

• Web applications: define browser-compatible output and module settings
• Node.js backends: choose CommonJS or ES modules and set output folders
• Libraries: control declaration file generation and compatibility targets
• Monorepos: keep compilation rules consistent across packages
• Build pipelines: ensure CI uses the same compiler settings as local development

Example scenarios

• A React app may use a config that supports modern JavaScript and JSX.
• An Express API may target a Node.js runtime and output files to dist.
• A shared package may enable declaration: true to generate .d.ts files.

In real projects, developers rarely stop at the default generated file. They usually customize it for the project structure and build process.

Common patterns include:

• Setting rootDir and outDir
  • Keeps source files in src and compiled output in dist
• Using strict mode
  • Helps catch bugs early
• Excluding generated folders
  • Prevents TypeScript from compiling node_modules, dist, or temporary files
• Creating base configs
  • Large teams often share a base tsconfig and extend it in subprojects
• Separate configs for app and tests
  • One config for production code, another for test tooling

Example real-world config

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

This is a common starting point for a Node.js TypeScript project.

1. Using tsc init instead of tsc --init

Broken command:

tsc init

Correct command:

tsc --init

Why it fails:

• init is a flag, not a subcommand.

2. TypeScript is not installed

If you see an error like tsc: command not found, TypeScript may not be installed.

Fix:

npm install --save-dev typescript
npx tsc --init

3. Running the command in the wrong folder

If you generate tsconfig.json in the wrong directory, your project may not use it.

Avoid this by:

• changing into the project root first
• checking that the file is created where your source code lives

4. Expecting tsconfig.json to compile files by itself

Creating the file does not compile your code. It only stores settings.

You still need to run:

tsc

5. Editing options without understanding them

Beginners sometimes copy a large config file from the internet and break their setup.

A better approach:

• start with tsc --init
• change only a few options at a time
• test after each change

tsc --init vs tsc

Global vs local TypeScript

Using npx tsc --init with a local install is usually the safest option.

# Install TypeScript locally
npm install --save-dev typescript

# Generate tsconfig.json
npx tsc --init

# Or if tsc is globally available
tsc --init

# Compile the project
tsc

Key rule

• Use --init, not init

What tsconfig.json does

• stores TypeScript compiler settings
• controls project compilation behavior
• lets tsc run without repeating many CLI flags

Common useful options

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true
  }
}

Common beginner workflow

1. Install TypeScript
2. Run npx tsc --init
3. Put source files in src
4. Run tsc
5. Check output in dist if configured

Edge cases

• If tsc is not found, install TypeScript first
• If multiple configs exist, make sure you are in the correct directory
• Creating tsconfig.json does not automatically run compilation

How do I create a tsconfig.json file in TypeScript?

Run:

tsc --init

If TypeScript is installed locally, use:

npx tsc --init

Why does tsc init not work?

Because init is not a standalone command. It must be passed as the --init flag.

Do I need to install TypeScript before generating tsconfig.json?

Yes. If tsc is unavailable, install TypeScript first:

npm install --save-dev typescript

Should I install TypeScript globally or locally?

Local installation is usually better for real projects because everyone on the team uses the same version.

Where is tsconfig.json created?

It is created in the current working directory where you run the command.

Can I write tsconfig.json manually?

Yes. It is just a JSON file. However, tsc --init is a convenient and safe starting point.

What happens after I generate tsconfig.json?

You can run tsc to compile your TypeScript files using the settings in that file.

• TypeScript compiler (tsc) — The command-line tool that reads tsconfig.json and compiles TypeScript.
• Compiler options — The settings inside tsconfig.json that control output and type checking.
• npx — A common way to run a locally installed TypeScript compiler.
• package.json scripts — Often used to store commands like build or typecheck.
• Module systems — Options like commonjs or esnext affect how compiled code is structured.
• Strict mode in TypeScript — A key compiler setting that improves code safety.
• Project structure (src and dist) — Common folders configured through tsconfig.json.