Setting Up Typescript Project

We built this so you don't have to. If you are starting a new application or converting an existing JavaScript codebase, you already know the drill: you spend the first three days fighting the compiler. You copy-paste a tsconfig.json from a StackOverflow thread dated 2019, you get hit with TS6059 errors because your baseUrl doesn't match your rootDir, and you spend hours debugging why your path aliases are broken in the IDE but work in CI.

We built the Setting Up Typescript Project skill to eliminate that friction. This is not a generic template. It is a validated, opinionated, multi-file scaffold that enforces modern TypeScript standards from the first commit. It handles the edge cases of module resolution, declaration generation, and strict mode that usually trip up working engineers.

The tsconfig Lottery Is a Waste of Engineering Time

The pain of a misconfigured TypeScript project is immediate and specific. You are not just writing code; you are configuring a build toolchain that dictates how your IDE, your linter, your test runner, and your bundler interact.

Most engineers start with a blank tsconfig.json and guess the flags. They enable strict: true but forget skipLibCheck: true, and suddenly their build is flooded with noise from node_modules. They set module: NodeNext but miss moduleResolution: NodeNext, and TypeScript throws TS5107 errors because the resolution strategy is outdated. They try to use path aliases for cleaner imports, but without a correct paths mapping in tsconfig.app.json, the compiler cannot resolve the modules, and your refactoring tools break.

This is not a theoretical problem. The TypeScript Handbook is clear that the compiler configuration is the foundation of your project ^[5]. If that foundation is shaky, every subsequent feature you build is built on sand. You end up with a project that feels fragile. You hesitate to merge PRs because you are afraid of breaking the build configuration. You spend more time reading compiler error messages than writing business logic.

The friction is compounded when you are migrating from JavaScript. You are already dealing with legacy code patterns, and a bad TypeScript setup amplifies the noise. You lose trust in the tooling. You start thinking TypeScript is too heavy, too complex, too slow. But the problem is not TypeScript. The problem is the lack of a standardized, validated starting point.

What Bad Defaults Cost You in P99 and Developer Trust

Ignoring a proper project setup has a tangible cost. It is not just "lost time." It is measured in hours, dollars, and downstream incidents.

Consider the cost of a single TS6059 error. This error occurs when a file is outside the root directory specified in tsconfig.json. Fixing it requires understanding the relationship between rootDir, outDir, and your file structure. If you have a large codebase, this error can cascade. You might spend 30 minutes just to realize that your src directory structure does not match the compiler's expectations. That is 30 minutes of flow state destroyed. Multiply that by 10 engineers on a team, and you are looking at days of lost productivity every sprint.

The cost extends to CI/CD as well. If your local setup differs from your CI setup, you get the "it works on my machine" syndrome. You might have a linter that passes locally but fails in the pipeline because the ESLint configuration is not aligned with the TypeScript compiler options. This erodes trust in the automation. Your team starts bypassing checks, leading to technical debt that compounds over time.

When you are migrating a JavaScript project, the stakes are higher. You need to ensure that your types are correct and that your module resolution works with both ESM and CommonJS if your dependencies require it. The TypeScript documentation highlights the differences between ES Modules and CommonJS, and getting this wrong can lead to runtime errors that are hard to debug ^[6]. You risk introducing regressions that only surface in production.

Furthermore, a bad configuration can break your IDE's ability to provide accurate autocompletion and refactoring. This slows down development significantly. You find yourself constantly checking the TypeScript compiler output to verify that your imports are correct. This is a massive drag on developer experience and productivity.

How a Clean Config Saves a Migration from Regression

Imagine a team that is starting a new microservice. They want to use TypeScript to catch errors early. They decide to use module: NodeNext for modern module support. They configure strict: true to enforce type safety. They set up path aliases to keep imports clean. Everything looks good in their local environment.

Then they try to add project references to share types between packages. They run into TS5107 errors because they are using an outdated module resolution strategy. They spend two days debugging the issue, only to realize that they need to update their tsconfig to use moduleResolution: NodeNext and handle the deprecation warnings correctly. They also discover that their baseUrl is misconfigured, causing TS6059 errors when they try to compile.

This scenario is common. The team is not bad at TypeScript; they just lack a validated starting point. They are reinventing the wheel every time they start a new project.

A better approach is to start with a configuration that has been tested and validated. Our skill provides a tsconfig.base.json that enforces modern standards, including module: NodeNext, moduleResolution: NodeNext, target: ES2022, and strict: true. It includes skipLibCheck: true to reduce noise and esModuleInterop: true for better compatibility with CommonJS modules. It also uses ignoreDeprecations: 6.0 to safely handle legacy flag transitions, ensuring that your project is future-proof.

The skill also provides a tsconfig.app.json that extends the base configuration and configures baseUrl, paths, rootDir, and outDir correctly. This ensures that your path aliases work and that your source-to-output mapping is correct. You can focus on writing code instead of debugging compiler errors.

When you are migrating a JavaScript project, this validated setup is even more critical. You can use the skill to initialize a new TypeScript project and then gradually migrate your code. The skill includes references to best practices for project structure and tooling, helping you make informed decisions about how to organize your codebase. It also provides examples of how to handle common TypeScript errors, such as TS5107 and TS6059, so you can resolve them quickly.

What Changes Once the Project Is Initialized

Once you install the Setting Up Typescript Project skill and run the initialization script, the difference is immediate. You have a project that is ready to develop, not a project that is ready to debug.

Your tsconfig.json is split into base and app configurations, following best practices for maintainability. The base configuration enforces strict mode and modern module resolution. The app configuration handles your specific project needs, such as path aliases and directory structure. This separation makes it easy to share configurations across multiple projects in a monorepo.

Your ESLint configuration is aligned with the TypeScript compiler. The skill provides a modern flat-config ESLint setup that integrates with the TypeScript ESLint parser and plugin. It enables recommended strict rules and configures Node.js globals, ensuring that your static analysis matches your compiler expectations. You no longer have to worry about ESLint and TypeScript disagreeing on your code style.

Your test runner is configured to work seamlessly with TypeScript. The skill sets up Vitest with a configuration that supports Node environment, global test utilities, and TypeScript path aliases. You can write tests that use your path aliases without any extra configuration. This saves you time and ensures that your tests are accurate.

The skill also includes a validator script that checks your tsconfig.json for critical flags. If any essential flags are missing or misconfigured, the validator exits with a non-zero status, preventing you from committing a broken configuration. This adds a layer of safety to your workflow and ensures that your project is always in a compilable state.

You can also reference the curated knowledge on TypeScript compiler configuration and project structure best practices. These references cover topics like module resolution, strict mode implications, path mapping, and tooling recommendations. They are based on official TypeScript documentation and provide authoritative guidance for making informed decisions.

The skill includes a worked example that demonstrates the full workflow. You can follow the example to run the initialization script, customize the configuration, run the validator, and integrate ESLint and Vitest. The example includes troubleshooting tips for common errors, making it easy to get started.

If you are also looking to Migrating Javascript To Typescript, this skill provides the foundation for a smooth transition. The validated configuration ensures that your types are correct and your module resolution works, reducing the risk of regressions. For a more comprehensive approach, you can also explore the TypeScript Migration Pack, which offers additional tools and scripts for migrating large codebases.

What's in the Pack

• skill.md — Orchestrator that defines the workflow for initializing a TypeScript project. Explicitly references templates/tsconfig.base.json, templates/tsconfig.app.json, templates/eslint.config.mjs, templates/vitest.config.ts, scripts/init-project.sh, validators/check-tsconfig.sh, references/compiler-options-reference.md, references/project-structure-best-practices.md, and examples/worked-example.md. Guides the AI on when to apply each component and how to chain them.
• templates/tsconfig.base.json — Production-grade base configuration enforcing modern TypeScript standards. Includes strict: true, module: NodeNext, moduleResolution: NodeNext, target: ES2022, declaration: true, sourceMap: true, skipLibCheck: true, esModuleInterop: true, resolveJsonModule: true, and ignoreDeprecations: 6.0 to safely handle legacy flag transitions per official compiler docs.
• templates/tsconfig.app.json — Application-specific configuration extending the base. Configures baseUrl: ., paths for module aliasing, rootDir: src, outDir: dist, and include: src. Demonstrates proper source-to-output mapping and path resolution to prevent TS6059 errors.
• templates/eslint.config.mjs — Modern flat-config ESLint setup tailored for TypeScript. Integrates @typescript-eslint/parser and plugin, enables recommended strict rules, and configures Node.js globals. Ensures static analysis aligns with ESM module expectations.
• templates/vitest.config.ts — Vitest configuration for high-performance unit testing. Sets up Node environment, enables global test utilities, and integrates with TypeScript path aliases for seamless test execution.
• scripts/init-project.sh — Executable shell script that automates project scaffolding. Creates src/dist directories, copies template configs, initializes package.json, installs pnpm/typescript/vitest/eslint dependencies, and triggers the validator.
• validators/check-tsconfig.sh — Programmatic validator that parses tsconfig.json using jq. Exits non-zero if critical flags (strict, moduleResolution, nodenext, declaration, sourceMap) are missing or misconfigured. Ensures compiler compliance before development begins.
• references/compiler-options-reference.md — Curated authoritative knowledge on TypeScript compiler configuration. Covers moduleResolution nodenext vs classic deprecation, ignoreDeprecations 6.0 usage, strict mode implications, paths/baseUrl mapping, rootDir/outDir constraints, and declaration/sourceMap generation. Extracted from official TypeScript compiler baselines.
• references/project-structure-best-practices.md — Curated knowledge on scalable TypeScript project architecture. Details ESM benefits for static analysis and IDE refactoring, monorepo path aliasing strategies, separation of persistence layers, and tooling recommendations (pnpm, Vite, clean-code-typescript ESLint presets).
• examples/worked-example.md — Step-by-step walkthrough demonstrating the full workflow. Covers running init-project.sh, customizing tsconfig.app.json for a specific app, running check-tsconfig.sh, and integrating ESLint/Vitest. Includes troubleshooting for common TS5107/TS6059 errors.

Install and Ship

Stop wasting time on boilerplate. Stop debugging tsconfig.json errors that should have been caught at initialization. Upgrade to Pro to install the Setting Up Typescript Project skill and ship a TypeScript project that is validated, opinionated, and ready for production.

The skill automates the setup, validates the configuration, and provides the references you need to make informed decisions. You can focus on writing code and building features, not fighting the compiler.

Antonio Evans is the Founder of Quanta Intelligence, the AI skill marketplace for coding agents. Connect on LinkedIn.

Published 2026-05-05, last updated 2026-05-05.