JS with Types Start

Reference

jsconfig.json options for JavaScript

A jsconfig.json is a tsconfig.json with JavaScript-friendly defaults. Most of TypeScript's options apply to it, but only some change anything in a project without .ts files; those are the ones documented here.

They are grouped by job: checking JavaScript, strictness, modules, the environment, and the files to check, followed by the comment directives that switch checking on or off inside a file. Where an option turns an error on or off, its page shows the same code passing one way and failing the other, both checked with tsc.

Checking JavaScript

The options that bring .js files into the program and check them, read types from JavaScript packages, and write .d.ts files for a package.

  • checkJs

    checkJs turns on TypeScript's error reporting for .js files. What it checks, how it relates to allowJs and // @ts-check, and how to switch it on.

    • Default false

  • allowJs

    allowJs brings .js files into the program so their types reach other files, without reporting errors in them. How it differs from checkJs.

    • Default false
    • true in jsconfig.json

  • maxNodeModuleJsDepth

    maxNodeModuleJsDepth sets whether TypeScript reads JavaScript packages in node_modules for types. jsconfig.json defaults it to 2, tsconfig.json to 0.

    • Default 0
    • 2 in jsconfig.json

  • noEmit

    noEmit makes tsc check your files and write nothing. A jsconfig.json defaults it to true; a tsconfig.json with allowJs needs it, or tsc stops with TS5055.

    • Default false
    • true in jsconfig.json

  • declaration and emitDeclarationOnly

    declaration and emitDeclarationOnly make tsc write .d.ts files from your JavaScript and its JSDoc, so a package written in JavaScript ships its own types.

    • Default false

  • skipLibCheck

    skipLibCheck skips checking every .d.ts file, your own included. A jsconfig.json turns it on by default, which can hide a typo in a .d.ts you wrote.

    • Default false
    • true in jsconfig.json

  • resolveJsonModule

    resolveJsonModule lets you import .json files and types their contents. nodenext and bundler turn it on; ES modules still need the json import attribute.

    • Default false

  • allowArbitraryExtensions

    allowArbitraryExtensions lets a .css or other non-JavaScript import use a declaration file such as theme.d.css.ts. Without it, that import is TS6263.

    • Default false

Strictness

strict and the checks it turns on, plus the stricter options it leaves off. Each page shows the same code passing with the option off and failing with it on.

  • strict

    strict turns on the strict type-checking family with one switch: nine options in TypeScript 5.9. What each catches in a .js file, and how to turn one back off.

    • Default false

  • noImplicitAny

    noImplicitAny reports values TypeScript can only type as any. In a .js file, that is mostly parameters with no JSDoc type and no default (TS7006).

    • Default false

  • strictNullChecks

    strictNullChecks makes null and undefined types of their own, so a value that may be missing is checked before use. It reports TS18047 and TS18048.

    • Default false

  • strictFunctionTypes

    strictFunctionTypes checks parameter types when one function type is assigned to another. A string-only function cannot stand in for one that gets numbers.

    • Default false

  • strictBindCallApply

    strictBindCallApply checks the arguments you pass through bind, call and apply against the function's own parameters, instead of accepting anything.

    • Default false

  • strictPropertyInitialization

    strictPropertyInitialization reports a class field that has a type but is never set, by an initializer or in the constructor (TS2564).

    • Default false

  • noImplicitThis

    noImplicitThis reports this inside a function where TypeScript cannot tell what it is (TS2683). In JavaScript, a @this tag says what it is.

    • Default false

  • useUnknownInCatchVariables

    useUnknownInCatchVariables types the err in catch (err) as unknown instead of any, so you check what was thrown before using err.message (TS18046).

    • Default false

  • alwaysStrict

    alwaysStrict parses every file in JavaScript strict mode, so reserved words such as package cannot be names. ES modules are strict anyway.

    • Default false

  • noUncheckedIndexedAccess

    noUncheckedIndexedAccess adds undefined to array elements and index-signature lookups, so names[2] must be checked before use. Not part of strict.

    • Default false

  • exactOptionalPropertyTypes

    exactOptionalPropertyTypes makes an optional property mean "may be missing", not "may be undefined", so { nickname: undefined } is TS2375.

    • Default false

  • noImplicitReturns

    noImplicitReturns reports a function where some paths return a value and others fall off the end (TS7030), a common source of a stray undefined.

    • Default false

  • noFallthroughCasesInSwitch

    noFallthroughCasesInSwitch reports a switch case that runs on into the next one without break or return (TS7029). Empty cases may still share code.

    • Default false

  • noImplicitOverride

    noImplicitOverride requires an @override tag on each method that replaces a base-class method, so renaming the base method cannot silently break it.

    • Default false

  • noUnusedLocals and noUnusedParameters

    noUnusedLocals and noUnusedParameters report variables, imports and parameters that are declared and never read (TS6133). A leading _ exempts a parameter.

    • Default false

  • noPropertyAccessFromIndexSignature

    noPropertyAccessFromIndexSignature makes you write obj["key"] rather than obj.key for keys that come from an index signature, such as process.env.

    • Default false

  • noUncheckedSideEffectImports

    noUncheckedSideEffectImports reports an import that binds nothing, like import "./polyfills.js", when its file is missing. On by default from TypeScript 6.0.

    • Default false

Modules and resolution

How the checker decides whether a file is an ES module or CommonJS, and how it finds the file or package behind each import.

  • module

    module tells the checker which module system your .js files follow: Node's rules with nodenext, a bundler's with preserve. Set it, even with noEmit.

    • Default commonjs

  • moduleResolution

    moduleResolution decides how the checker finds the file behind an import: Node's rules with nodenext, a bundler's with bundler. Usually module sets it for you.

    • Default node10

  • moduleDetection

    moduleDetection decides which files are modules with their own scope. With bundler settings, force stops scripts from sharing one global scope (TS2451).

    • Default auto

  • esModuleInterop and allowSyntheticDefaultImports

    esModuleInterop and allowSyntheticDefaultImports let you write import express from "express" for a CommonJS package. A jsconfig.json already allows it.

    • Default false

  • paths and baseUrl

    paths maps import names to files for the checker, such as @lib/* to src/lib/*. It does not change how Node.js resolves imports; package.json imports does.

    • Default not set

  • customConditions

    customConditions adds export conditions, like development, that TypeScript uses when it reads a package's exports map. Match what your runtime or bundler uses.

    • Default not set

  • verbatimModuleSyntax

    verbatimModuleSyntax keeps imports exactly as written in tsc's output. In a .js project its one effect is to report ESM exports in a CommonJS file.

    • Default false

Environment

Which JavaScript version and which globals the checker assumes: target, lib, types, JSX, and file name casing.

  • target

    target names the JavaScript version your runtime has. With noEmit it picks which built-in APIs exist: Promise.withResolvers needs es2024.

    • Default es5

  • lib

    lib picks the built-in declarations the checker knows: an ECMAScript year, and dom for browsers. Without dom there is no document, and no console either.

    • Default the target's libraries, plus dom

  • types and typeRoots

    types lists the @types packages whose globals the checker loads, like node for process. Without it, TypeScript 5.9 loads every @types package; 6.0 loads none.

    • Default every package in node_modules/@types

  • jsx

    jsx lets the checker read JSX in .jsx files. Without it, any JSX is TS17004; with it, elements and props are checked against your framework's JSX types.

    • Default not set

  • forceConsistentCasingInFileNames

    forceConsistentCasingInFileNames reports an import whose letter case differs from the file name, which works on macOS and Windows and fails on Linux.

    • Default true

Files

The top-level keys that pick the files to check, and extends for sharing one config between several.

  • include

    include lists the files and folders the checker starts from, as globs relative to jsconfig.json. A folder name picks up every .js file under it.

    • Default ["**/*"]

  • exclude

    exclude removes files from what include matched. It does not keep a file out of the program: an imported file is still read, and with checkJs, still checked.

    • Default ["node_modules", "bower_components", "jspm_packages"]

  • files

    files names the exact files the checker starts from, with no globs. Files they import are checked too, and a missing file is a config error.

    • Default not set

  • extends

    extends makes a config inherit another config file's options, so several jsconfig.json files can share one base. Files lists are replaced, not merged.

    • Default not set

Comment directives

Not options: comments in a .js file that turn checking on or off for that file, or silence one line.

  • // @ts-check

    // @ts-check at the top of a .js file turns on type checking for that one file, even with checkJs off. Where to put it, and when to use it instead of checkJs.

    • Whole file

  • // @ts-nocheck

    // @ts-nocheck at the top of a file turns checking off for that file while checkJs stays on for the rest. The file's types still reach its importers.

    • Whole file

  • // @ts-ignore

    // @ts-ignore silences every error on the next line, now and later. Prefer // @ts-expect-error, which tells you when there is nothing left to silence.

    • Next line

  • // @ts-expect-error

    // @ts-expect-error silences the errors on the next line, and reports TS2578 once that line has none, so a fixed problem cannot leave a stale comment.

    • Next line

The entries on this page are also published as data: config-options.json (about the data files).