Review the project setup experience

[DanielRosenwasser]

Today, tsc --init creates a big-ol' file that is super intimidating. We try to provide comments and blocks of sections to give people a clear separation of config concerns. We also provide a link to https://aka.ms/tsconfig.json.

We also have a belief that most people don't even use tsc --init.

That said, there are problems, and tsc --init doesn't make it totally clear what the "best practices" are for starting a project. Things that are missing:

• Project layout guidance (e.g. src, tsconfig naming)
• "well known"/"blessed" flags as opposed to just ONE BIG PAGE of ALL THE FLAGS 😨
• Easy way to find the information regardless of whether a user used tsc --init

In short:

• Docs for tsconfig.json "getting started"
• Link to that in generated tsconfig.json
• Re-evaluate generated tsconfig content.

[orta]

Possible spaces for exploration:

• Make it interactive and/or rely on @tsconfig/bases for examples to work from
• A different way to show groups of common tsconfig options (e.g. "these are all the things most node projects use") in the reference
• Better categorization of tsconfig opts

[RyanCavanaugh]

Just throwing out what I myself would want to happen, tsc --init should give me (in order):

• All of the "you need to tell us" settings written out at the top (target, module, etc)
• Opinionated defaults where necessary to prevent undesirable behavior (e.g. `outDir: "./lib" to prevent in-placing .js files)
• All of our "recommended" options in a block with "We recommend these settings for new projects"
• The most-commonly-changed settings (lint-ish rules, etc) after that

[AlCalzone]

* Make it interactive

My first thought, too. You could ask the user...
...what runtime he is targeting (Browser w/ or w/o React, Node.js)
...which minimum version (e.g. to set up target/lib)
...whether potential undefined values should be flagged (to nudge users towards the goodness that is hidden behind the somewhat intimidating name --strict)
...etc

[SagnikPradhan]

Making a minimal interactive command similar to that of eslint can be an interesting option too.

[softwareCobbler]

I figure you have telemetry for this; but one more datapoint for you: I use tsc --init all the time and just "uncomment out" all the strict options. Max safety, I want all the red squigglies and inference you can muster.

[renanmontebelo]

I like the fact that tsc --init generates a file with all flags explicitly listed, even if most are commented out. However, I was surprised today when I noticed the commented out flags do not necessarily reflect default values. For instance, the following line is generated

// "sourceMap": true, /* Generates corresponding '.map' file. */

when the actual default value is false. My suggestion is that these values should reflect default values and hence be fully self-documented (no need to visit a webpage to check what the default values are).

[Jack-Works]

Another problem is that when upgrading, there isn't a "tsc --upgrade" command to add new flags into the tsconfig.json

[voxpelli]

The default value of some of the flags is also confusing for people who are new to the flags and trying to set it up for themselves manually or through tsc --init, many assuming that flags are used to deviate from the recommended route, not used to stick to the recommended route. See eg. #41139

[fgarcia]

Probably not related with the "initial setup" but I've long wished an easier way for the user to enable strict flags. Something like enable globally strict null checks but only report (or hide) reports for specific paths

I could create a new Typescript configuration extension file for each folder with code that is stable/mature enough, but that just forces me to over complicate my setup. Also I have yet to find a way to make VsCode cooperate with multiple Typescript configurations

Enabling the user to enjoy the benefits of strict typing (in part of their code) without investing too much time in advanced configuration topics might be consider a better setup experience.

[Jack-Works]

what about

> tsc init --modern # create a new file
> tsc init --upgrade # run to upgrade existing tsconfig.json to enable all suggested options

[bbenoist]

Good issue! I had a poor experience the last time I had to tsc --init... The last time I had to init a tsconfig shouldn't be something which I remember 😢

While you're working at it, here are some ideas/suggestions:

• As suggested, it might be nice to have some sort of Yeoman-like interactive mode by default if we don't pass-in arguments to tsc init.

• If you go to the interactive way, try to ask questions with pragmatic guidance about the common important choices.

• If you stay with the commented-file option, please don't put comments at the end of lines. It's a pain to clean.

• Why not proposing some presets for the most common environments? For newcomers, there is already enough to learn for not bothering with compiler options. Adding TypeScript to the equation would still add an extra-layer of complexity.
  As an example, a few years ago, I came from the C++ world with everything to learn. Back to those days, choosing the target ES version or module resolution seemed like if I would never quit software with build-systems more complex than their own code😅

[Kinrany]

It would be great to opt into using the latest recommended options as defaults, instead of updating manually (even with tsc --upgrade).

Something like "extends": "recommended".

This is perfectly OK for reproducible builds if the recommended settings only change with compiler versions.

This would also make the generated tsconfig smaller for those who are OK with fixing errors right away or disabling the new options explicitly.

[max-hk]

FYI, I use Next.js's tsconfig (with minor changes) in both Node.js or browser based projects and it works great.

I think it is a good boilerplate to start with.