tsc --init update 2024

[RyanCavanaugh]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

Following up from #58417

Note: This is only for argumentless tsc --init. We know that it's physically possible to write text after --init and that text could do something, but that's a separate issue. Since tsc --init should do something, this issue is only about what that something is.

General consensus from the design meeting + external discussion:

• No one likes the huge wall of text
• Not many people like the commented-out options, and certainly not the "terrible idea" commented-out options
• "module": "commonjs" is a hard no

Other live issues:

• Should we set '"types": []' for 'tsc init'? #39354 - set types to [] - yes
• Increase default tsc --init target over time #49206, Make tsc --init generate default target to ES6 or higher #39308 - increase default target - also yes
• Enable "useDefineForClassFields" in tsc --init #39311 - set udfcf - I would argue moot by now since we should set the target high enough that this doesn't matter
• Consult package.json contents when creating tsconfig.json under tsc --init to determine better defaults #51207 - consult package.json - it's not obvious that your package.json is configured yet at the time you run tsc --init, this seems marginal

Other things we didn't get to:

• rootDir, outDir: These are generally a good idea; no one likes the default side-by-side JS emit buuut there aren't strictly universal conventions here

Proposed new output:

{
    // For more info, see https://aka.ms/tsconfig
    // Or use the tsc-init wizard: https://aka.ms/tsc-init
    "compilerOptions": {
        "target": "es2022",
        "module": "nodenext",
        "rootDir": "./src",
        "outDir": "./dist",

        // For nodejs, add "node" to this array,
        // and remove "dom" from "lib"
        "types": [],
        "lib": ["dom", "es2022"],

        // Other outputs
        "sourceMap": true,
        // "declaration: true,

        // Typechecking options
        "noUncheckedIndexedAccess": true,
        "exactOptionalPropertyTypes": true,

        // Style options
        // "noImplicitReturns": true,
        // "noImplicitOverride": true,
        // "noUnusedLocals": true,
        // "noUnusedParameters": true,
        // "noFallthroughCasesInSwitch": true,
        // "noPropertyAccessFromIndexSignature": true,

        // We recommend all of these options
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "moduleDetection": "force",
        "skipLibCheck": true,
        "strict": true
    }
}

I tried to order this from "most likely to edit" to "least likely to edit"

[andrewbranch]

Module options look good to me for Node.js / library authoring. I assume you’ve intentionally left in some redundancies so that good option A stays set if someone changes/removes option B that’s currently making A redundant. For good measure, a list of those:

• --module nodenext implies --target esnext; you have it set to es2022 (seems good to keep it set as is)
• --module nodenext implies --moduleDetection force
• --verbatimModuleSyntax implies --isolatedModules (people are more likely to turn off the former)

The one that’s missing from this good-but-redundant category is --module nodenext implies --esModuleInterop, which is a good idea to keep on, but the thing people are likely to switch to is --moduleResolution bundler, which implies --allowSyntheticDefaultImports, which is close enough. So not critical to add, I think.

TLDR looks good 👍

[DanielRosenwasser]

Though originally I was thinking more about include over rootDir, it makes sense given the guardrails rootDir provides if you screw something up? And that's important given people try to do custom exclude/include rules that are often unnecessary.

So I'm generally in favor around outDir and rootDir. The thing I am curious about is if we can detect sensible conventions such as folder name and existence of a package.json. This includes stuff like src as a well-known input directory, and special casing depending on if you're running from inside src.

[RyanCavanaugh]

👍 / 👎 ?

        // Other outputs
        // "declaration": true,
        // "sourceMap": true,

[andrewbranch]

Pretty much everybody is going to debug at some point, and it’s going to be bad until they realize they need to enable sourceMap

[fatcerberus]

The only thing that sucks about having options commented out is you can't hover on them to see the description of what they do, which doesn't help when you don't know what something does and want to know if you should enable it. Unfortunately most options don't have an explicit setting that means "use the default behavior, whatever it happens to be today", so no easy solutions to be found here.

[Conaclos]

I could also suggest turning off allowUnreachableCode. It greatly help in some circumstance.

[System233]

My suggestion is that the tsconfig should only configure basic type checking and avoid trying to add things that users may need. Developers will refer to the documentation to configure what they really need; there's no need to overcomplicate things.

In China, there’s an idiom called “画蛇添足,” which literally means adding feet to a snake while drawing it. This idiom refers to the act of making unnecessary additions that complicate things rather than enhancing them. Adding a lot of options and comments that no one knows who will use or when they will be used exemplifies this unnecessary complication. Attempting to predict developers' environments to generate targeted default configurations and comments will never satisfy everyone. Since that’s the case, why not keep things a little simpler? Therefore, only the most basic configurations should be added, representing the minimal TS/JavaScript development environment. As for what specific options developers actually need, that’s not something we should be concerned about. Regarding the option comments in tsconfig, simply replacing them with a $schema field would suffice; don’t treat developers like idiots, managing them like a nagging mother.

[RyanCavanaugh]

{
    // For more info, see https://aka.ms/tsconfig
    "compilerOptions": {
        // File layout
        "rootDir": "./src",
        "outDir": "./dist",

        // Environment settings
        // See also https://aka.ms/tsconfig_modules
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        // For nodejs:
        // "lib": ["esnext"],
        // "types": ["node"],
        // and npm install @types/node

        // Other outputs
        "sourceMap": true,
        // "declaration: true,

        // Stricter typechecking options
        // "noUncheckedIndexedAccess": true,
        // "exactOptionalPropertyTypes": true,

        // Style options
        // "noImplicitReturns": true,
        // "noImplicitOverride": true,
        // "noUnusedLocals": true,
        // "noUnusedParameters": true,
        // "noFallthroughCasesInSwitch": true,
        // "noPropertyAccessFromIndexSignature": true,

        // We recommend all of these options
        "strict": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "moduleDetection": "force",
        "skipLibCheck": true
    }
}

[DanielRosenwasser]

^ One issue with the above is that rootDir doesn't necessarily modify include, and as a result, a compilation can still include files outside of src while issuing an error. Not sure if it's just worth specializing the error message there.

[ArnaudBarre]

I think noFallthroughCasesInSwitch should be recommended. It can be a "style" to work with fall through, but I think for most people it would catch bugs

Also I would love this starter to document how to configure TS for bundlers:

/* If you compile/transpile your code with TS */
"outDir": "./dist",
"sourceMap": true,
// "declaration: true, // emit d.t.s

/* If you compile your code with a bundler, remove the section above and uncomment this one: */
// "moduleResolution": "bundler",
// "allowImportingTsExtensions": true,
// "noEmit": true,

[justinfagnani]

I'd like to put in a pitch for "outDir": "./"

That's often the right value if you're migrating from JS and want to keep the same file layout, and it's also what you want to do if you have things like a top-level index.js, and non-distributed files like tests, tool configs, demos, and local scripts.

Your src/ folder might look like:

src
├── demo
│   └── index.ts
├── lib
│   └── foo.ts
├── scripts
│   └── cleanup-things.ts
├── test
│   └── foo_test.ts
└── index.ts

And index.js and lib/* would be the only output files "distributed".