<h3>What is tsconfig.json?</h3>
The <code>tsconfig.json</code> file is the “recipe book” of the TypeScript compiler. It tells TypeScript how to “cook” your code: which ingredients (options) to use, how long to simmer (compile), and where to serve the final JavaScript output. Without it, a TypeScript project is like a chef without a recipe—chaos and confusion reign.
<hr>
<h3>Key Sections of tsconfig.json</h3>
<h4>1. <code>compilerOptions</code> — The “Recipe Book”</h4>
This section holds all critical compilation settings. Examples include:
<ul>
<li>
<code>target</code>: Specifies the JavaScript version to transpile to (e.g., <code>ES5</code>, <code>ES2020</code>). 
Metaphor: Like choosing the difficulty level of a recipe—from basic (ES5) to modern (ES2020).
</li>
<li>
<code>module</code>: Defines the module system (CommonJS, ES6). 
Example: <code>module: &quot;ESNext&quot;</code> uses the latest experimental modules, as if you’re on the tech frontier.
</li>
<li>
<code>strict</code>: Enables “strict mode,” enforcing type safety and optional fields. 
Association: Imagine your code attending school with a meticulous teacher.
</li>
<li>
<code>outDir</code> and <code>rootDir</code>:
<ul>
<li><code>rootDir</code>: The root of your raw TypeScript code.</li>
<li><code>outDir</code>: The folder for the compiled JS output. 
Metaphor: Think of <code>rootDir</code> as the kitchen door and <code>outDir</code> as the buffet where dishes are served.</li>
</ul>
</li>
</ul>
<h4>2. <code>include</code>, <code>exclude</code>, <code>files</code> — The “Shopping List”</h4>
<ul>
<li>
<code>include</code>: Lists directories/files to compile. 
Example: <code>include: [&quot;src/**/*&quot;]</code> compiles everything in the <code>src</code> folder.
</li>
<li>
<code>exclude</code>: Excludes files (e.g., <code>node_modules</code>). 
Association: A list of ingredients forbidden in the recipe.
</li>
<li>
<code>files</code>: Explicitly lists specific files. 
When to use? For small projects or when precise control is needed.
</li>
</ul>
<hr>
<h3>Advanced Settings</h3>
<h4>1. Paths and Aliases (<code>baseUrl</code>, <code>paths</code>)</h4>
<ul>
<li>
<code>baseUrl</code>: Sets the base directory for relative imports. 
Example: Set <code>baseUrl: &quot;src&quot;</code> to import like <code>import MyComponent from 'components/MyComponent'</code>.
</li>
<li>
<code>paths</code>: Creates aliases to simplify imports. 
Example:
<pre><code class="language-json">&quot;paths&quot;: {
 &quot;@models/*&quot;: [&quot;src/models/*&quot;]
}
</code></pre>
Metaphor: Like creating shortcuts in a file explorer—faster and cleaner.
</li>
</ul>
<h4>2. Compilation Optimization</h4>
<ul>
<li><code>watch</code>: Auto-recompiles on file changes.</li>
<li><code>incremental</code>: Saves intermediate results to speed up future builds.</li>
<li><code>build</code>: Multi-project builds (ideal for libraries).</li>
</ul>
<hr>
<h3>Practical Examples</h3>
<h4>1. Simple Project</h4>
<pre><code class="language-json">{
 &quot;compilerOptions&quot;: {
 &quot;target&quot;: &quot;ES2020&quot;,
 &quot;module&quot;: &quot;ESNext&quot;,
 &quot;strict&quot;: true,
 &quot;outDir&quot;: &quot;./dist&quot;
 },
 &quot;include&quot;: [&quot;src/**/*&quot;]
}
</code></pre>
<h4>2. Library with Aliases</h4>
<pre><code class="language-json">{
 &quot;compilerOptions&quot;: {
 &quot;baseUrl&quot;: &quot;.&quot;,
 &quot;paths&quot;: {
 &quot;@utils/*&quot;: [&quot;src/utils/*&quot;]
 },
 &quot;declaration&quot;: true // Generates `.d.ts` files for publishing
 }
}
</code></pre>
<hr>
<h3>Key Takeaways</h3>
<ol>
<li><code>tsconfig.json</code> is the heart of a TypeScript project. Proper setup saves time and prevents errors.</li>
<li>Strict mode (<code>strict</code>) is your friend if you want to avoid “silent” bugs.</li>
<li>Aliases (<code>paths</code>) make imports cleaner and simplify refactoring.</li>
<li>Optimization flags (<code>watch</code>, <code>incremental</code>) are vital for large projects.</li>
<li>Understanding <code>outDir</code> and <code>rootDir</code> avoids path confusion.</li>
</ol>
<hr>
<h3>How to Get Started?</h3>
<ol>
<li>Create a <code>tsconfig.json</code> using <code>tsc --init</code>.</li>
<li>Start with basics: <code>target</code>, <code>module</code>, and <code>strict</code>.</li>
<li>Add <code>include</code> and <code>exclude</code> to control compilation.</li>
<li>Experiment with aliases and optimizations as your project grows.</li>
</ol>
<hr>
<code>tsconfig.json</code> isn’t just a file—it’s a project management strategy. When configured correctly, it turns chaos into structure and bugs into opportunities for improvement.

The official daily.dev web development community. Led by thought leaders and webdev experts. Join the Squad!

WebDev

Mastering tsconfig.json in TypeScript

Using cooking as a metaphor was hilarious and genuinely genius at the same time 😀. Good summary. In my opinion ot would be beneficial to also write a bit about in more detail what are the different things you can put on the right side of the assignment. Like what are the different types of modules, etc.

Another tip for bigger codebases is combining <code>composite: true</code> with project references. This keeps incremental builds snappy across multiple packages while still letting each team own its own “recipe book.” It might be worth mentioning for folks building mono-repos or libraries.

I really like this article. It made so much sense to me.

This made me realize my tsconfig.json is basically Gordon Ramsay yelling at my TypeScript until it compiles properly. “It’s RAW! You forgot ‘strict: true’ again!!” 🍳😂

This is awesome, it is easier to grasp how things work. keep it up