tsconfig & Compilation
You will learn how tsconfig.json actually shapes a TypeScript project: which flags tighten type checking, how the compiler resolves module specifiers and picks an output target, how declaration files are produced and consumed, and how type-checking fits into a real build. Interviewers ask because most TypeScript setup pain — 'cannot find module', 'it compiles locally but not in CI', a published package with no types — traces straight back to a compiler option nobody on the team understood.
part ofTypeScriptread it →on this pageshowhide
explore
- Strictness & Correctness Flags15 questions
- The strict Family5 questions
- Correctness Flags Beyond strict5 questions
- isolatedModules & verbatimModuleSyntax5 questions
- Modules, Targets & Resolution11 questions
- target, module & lib6 questions
- moduleResolution, Interop & Path Mapping5 questions
- Declaration Files & Publishing18 questions
- Emitting & Shipping .d.ts6 questions
- Ambient Declarations & Augmentation6 questions
- Namespaces vs ES Modules6 questions
- JavaScript Interop & Migration10 questions
- allowJs, checkJs & JSDoc Typing5 questions
- Incremental Migration Strategy5 questions
- Build Topology & Toolchain10 questions
- Project References & Incremental Builds5 questions
- Transpile-Only Pipelines & Type-Check Gates5 questions
questions
64 · 5 sectionsIn TypeScript, what does `import type { User } from './models'` mean, and how does it differ from a plain `import { User } from './models'`?
basics
~20 simport type declares the binding as types only: TypeScript always erases that statement from the emitted JavaScript, and the name cannot be used as a value. A plain import is erased only when the compiler decides nothing in the file uses it at runtime.
With TypeScript's noImplicitAny flag enabled, why does `function greet(name) {}` fail to compile while the `u` in `users.map(u => u.id)` needs no annotation at all?
basics
~20 snoImplicitAny only errors where the compiler has no type to infer. A standalone parameter has no source of type information, so it would silently become any; a callback parameter is contextually typed from the signature it is passed to, so its type is inferred rather than implicit.
What does TypeScript's `isolatedModules` compiler flag do, and does enabling it change the JavaScript that `tsc` emits?
basics
~20 sisolatedModules changes no output at all. It is a checking-only flag: it makes the compiler report source constructs that cannot be compiled correctly by a tool that sees one file at a time, so the code stays portable to per-file transpilers.
In a TypeScript project's tsconfig.json, what does setting "strict": true actually do, and how would you keep it on while turning off just one of the checks it implies?
basics
~20 sThe strict option in tsconfig.json is not one check: it is a shorthand that switches on a whole family of individual flags, including noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, useUnknownInCatchVariables and alwaysStrict. Setting any member explicitly overrides the umbrella.
In a TypeScript tsconfig.json, does setting "strict": true turn on every correctness check the compiler offers? Name checks it leaves off and explain why they are separate options.
basics
~10 sNo. strict switches on one fixed family of type-soundness options; a separate set of correctness checks stays off until you list each one by name, including noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride, noImplicitReturns, noFallthroughCasesInSwitch and noUnusedLocals.
In TypeScript, when you write `import _ from 'lodash'`, where does the compiler look for that package's type declarations, and what does the error "Could not find a declaration file for module 'lodash'" mean?
basics
~20 sThe compiler looks inside the package first — package.json's types or typings field, or a types condition in its exports map — then falls back to node_modules/@types/lodash. If neither exists, the import carries no type information.
In a tsconfig.json, what does the `target` compiler option control and what does the `module` option control, and why can you not use one in place of the other?
basics
~20 sIn tsconfig, target sets the language level of the emitted JavaScript syntax, deciding whether things like async/await or optional chaining get rewritten. module sets the output module format, such as CommonJS require and exports or untouched ESM. The two are independent.
A tsconfig.json sets `"paths": { "@app/*": ["src/*"] }` and `tsc` compiles with no errors, but running the emitted output with `node dist/index.js` fails with "Cannot find module '@app/utils'". Why does the compiler accept a specifier the runtime rejects?
basics
~20 sBecause paths is a type-checker-only mapping. The compiler uses it to find declarations for the specifier, but it never rewrites import specifiers in the emitted JavaScript, so the output still says '@app/utils' and the runtime has no idea what that means.
A tsconfig sets `"target": "es5"` and `"lib": ["ES2020", "DOM"]`. A call to `[1, [2]].flat()` type-checks cleanly but throws `TypeError: ...flat is not a function` in an old browser. Explain what target and lib each do, and how you would fix this.
basics
~20 starget controls emitted syntax; lib only tells the checker which built-in APIs it should believe exist. TypeScript never emits polyfills, so declaring ES2020 libs while running on an older engine type-checks calls like Array.prototype.flat that then crash at runtime.
In tsconfig.json, what is the difference between the `esModuleInterop` and `allowSyntheticDefaultImports` compiler options?
basics
~20 sallowSyntheticDefaultImports is type-checking only: it lets you write a default import from a module that declares no default export. esModuleInterop additionally changes CommonJS emit to wrap the required value, and it turns allowSyntheticDefaultImports on for you.
In a TypeScript library's tsconfig.json, what does the `declaration` compiler option emit, and why does a package that already ships compiled JavaScript still need that output?
basics
~20 sThe declaration option makes tsc emit .d.ts files next to the JavaScript. Compilation erases types, so the .js carries none; the .d.ts is the type-only mirror that gives consumers of the published package autocomplete and type checking.
In TypeScript, a file `globals.d.ts` containing only `interface Window { analytics: Analytics }` successfully adds `window.analytics` across the project. After you add `import type { Analytics } from './analytics'` to the top of that same file, every use of `window.analytics` starts failing. What changed, and how do you fix it?
basics
~20 sThe top-level import turned that declaration file from a global script into a module, so its interface no longer merges with the global Window. Wrap the declaration in declare global inside the module to reach the global scope again.
In TypeScript, how do you add a property to an interface exported by a third-party package's type declarations — say adding `user` to a framework's `Request` interface — without forking or copying that package's types, and what does the compiler require of the file you write it in?
basics
~10 sUse module augmentation: in a file that is already a module, write declare module 'the-package' and re-open the exported interface with your extra members. Interface merging adds them everywhere the package's types are used.
In a TypeScript project, importing an npm package that ships only JavaScript fails with "Could not find a declaration file for module ...". What is an `@types/*` package, how does the compiler find one, and what problems does that split introduce?
basics
~20 sAn @types/* package contains only declaration files for a library that ships none, published from the community DefinitelyTyped repository. TypeScript looks for it in node_modules/@types. Because it is versioned and maintained separately from the library, it can drift out of sync.
In a TypeScript project, `import styles from './Button.module.css'` fails with "Cannot find module './Button.module.css' or its corresponding type declarations." How do you make the compiler accept that import, and does your fix change anything at runtime?
basics
~20 sAdd a wildcard ambient module declaration in a .d.ts file the project includes: declare module '*.module.css' with a default export of a string-to-string map. That only satisfies the type checker — a bundler or loader must still make the import work at runtime.
In a tsconfig.json, what does the TypeScript compiler option `allowJs` do on its own, and what changes when you also turn on `checkJs`?
basics
~20 sallowJs admits .js and .jsx files into the TypeScript program so they are resolved, inferred from and emitted — but no errors are reported in them. checkJs additionally turns the type checker on for those JavaScript files.
In TypeScript, what is the difference between the `// @ts-expect-error` and `// @ts-ignore` comments, and why is one usually preferred?
basics
~20 sBoth suppress type errors on the line that follows them. // @ts-expect-error additionally requires an error to be there — if the line becomes valid, the compiler reports the directive as unused, so stale suppressions surface instead of rotting.
In a JavaScript file that TypeScript is checking, how do you annotate a function's parameters and return type, declare a reusable named object type, and make a function generic — using only JSDoc?
basics
~20 sUse JSDoc tags in comments: @param and @returns for a function's signature, @type for a variable or a cast, @typedef to declare a reusable named type, and @template to introduce a type parameter. TypeScript reads them as real types.
In a project already compiled by tsc with allowJs enabled, you rename utils.js to utils.ts and change nothing inside the file. Does the JavaScript that ships behave any differently, and what does change?
basics
~20 sBehaviour does not change: TypeScript erases types, and a freshly renamed file has none to erase, so tsc emits the same JavaScript. What changes is checking — the file is now checked as TypeScript, so implicit anys and unsound patterns start appearing as errors.
What do the `// @ts-check` and `// @ts-nocheck` comments do when placed at the top of a file, and how do they interact with TypeScript's `checkJs` compiler option?
basics
~20 sPlaced at the top of a file, // @ts-check makes TypeScript type-check that one file even when checkJs is off, and // @ts-nocheck makes it skip that file even when checking is on. Both override the project setting per file.
In a tsconfig.json, what does setting `"composite": true` turn on, and what does the compiler then require of that project?
basics
~20 scomposite: true marks a tsconfig.json as a buildable unit that other projects can reference. It forces declaration on, enables incremental build info, defaults rootDir to the config's directory, and requires every input file to be matched by files or include.
What does running `tsc --build` (`tsc -b`) do that plain `tsc -p tsconfig.json` does not?
basics
~20 sBuild mode walks the references graph: it builds each referenced project first, in dependency order, and skips any project whose outputs are already newer than its inputs. Plain tsc -p compiles only the one project and assumes its dependencies are already built.
A project bundles its TypeScript with esbuild, and the build succeeds and ships even though the source contains type errors. Why does esbuild not fail on them, and what command do teams run to catch them instead?
basics
~20 sesbuild only strips type annotations file by file; it never runs TypeScript's type checker, so type errors cannot fail it. Teams add a separate step running tsc --noEmit, which type-checks the whole program and writes no output.
In a TypeScript project, what does the `extends` field in tsconfig.json do, and relative to which directory are relative paths written inside the inherited base config resolved?
basics
~20 sThe extends field makes a tsconfig.json inherit another config file's settings, which the local file can then override key by key. Relative paths written in the base file resolve against the base file's own directory, not the inheriting project's.
Running a script with tsx succeeds, but running the same file with ts-node fails with a type error before anything executes. What is different about how the two tools run a TypeScript file?
basics
~20 sts-node type-checks with the real TypeScript compiler before running, so a type error stops it. tsx uses esbuild to strip types with no checking, so it runs whatever parses. ts-node's --transpileOnly flag makes it behave like tsx.