Add support for a .tsconfig file

[mhegazy]

Typescript compiler lacks a native way of maintaining compilation options and source files for a given compilation unit like a project or a module. Using /// can help ease the problem, but there is still a tax of adding and managing the references and it does not handle the compilation options issue. Moreover, different editors have different ways of representing project or module structure and compilation options which make cross-editor collaboration tricky.

The proposal is to introduce a new file .tsconfig that marks a compilation unit (aka project or module). The .tsconfig follows the footsteps of the .git* file family. Calling tsc in a directory with a .tsconfig will use the contents of the file and all .ts files in the directory as inputs without the need to specify them on the command line again.

.tsconfig in detail

• .tsconfig is a json file
• The presence of a .tsconfig in a directory indicate that all .ts file in this directory and its sub directories recursively are part of the compilation unit
  • .d.ts files generated from the compilation but live within the directory are not included in the compilation unit identified by .tsconfig
• .tsconfig can specify additional compilation settings for the compilation
• Calling tsc in a folder containing .tsconfig will trigger compilation using the config file
• Since .tsconfig is a json file, it can be leveraged by other tools (linters, editors, build tools etc..) to store TS related project configuration
• Example .tsconfig

{
    "compilerOptions": ["-t ES5", "--out myoutput.js", "--noImplicitAny"],
    "linterOptions": {
        "suppressWarnnings": [234, 3363] 
    }
}

Module example

Consider the following directory structure:

shared/
    node.d.ts
    tools.ts
foo/
    .tsconfig
    a.ts // adds a ///<reference> to node.d.ts 
    b.ts
bar/
    .tsconfig
    c,ts // adds a /// <references> to tools.ts
    d.ts
    baz/
        e.ts

Calling tsc in "foo" is equivalent totsc a.ts b.ts
Calling tsc in "bar" is equivalent to tsc c.ts d.ts baz/e.ts

Using .tsconfig with tsc

• When calling tsc with no input files, the following steps are taken:
  1. Find the owning .tsconfig file by walking up the directory structure until a .tsconfig file is found, or the drive root is reached
  2. If a .tsconfig was found, compilation will be triggered with all .ts files in the directory containing the .tsconfig and all its sub directories
  3. The command line switch are compiled with the configuration options from the .tsconfig defining the compilation command line flags (e.g.: tsc --watch will cause a tsc to compile the contents of the current project in watch mode)
• When calling tsc with input a single directory name (e.g.: tsc compiler), If the directory contains a .tsconfig at the root, steps 2 and 3 from above are followed.

Specifying output order with --out and .tsconfig

when using --out, the compiler relies on the order of the files passed on the command line to order the emitted JavaScript code. If using .tsconfig, the compiler will look for a special file _references.ts at the root (next to the .tsconfig file), and will ensure that this file is the first file in the list of input files. this implies that /// tags in _references.ts will specify order of the emitted files.

Open issues:

1. Should the tsconfig file have a .json extension to indicate intended content, and allow editors to correctly colorize it, format it, etc..
2. In a VS project context (say .csproj), should .tsconfig be honored, or ignored in favor of the project.

[Arnavion]

• It would be nice if "compilerOptions" was an object like { "t": "ES5", "noImplicitAny": true } instead of an array of strings (essentially the CompilerOptions interface but with strings instead of enums). This is similar to how the grunt plugin, etc. are configured. See this and this.
• What options should not be honored in a .tsconfig ? For example, I don't know if anyone will ever want "watch" to be a default behavior of running tsc under their project directory, so even if .tsconfig contains "watch" it should be ignored?

[DanielRosenwasser]

Great writeup @mhegazy. A few questions/concerns:

Are we not going to be able to specify TypeScript files in the config file? Perhaps this is something for down the road instead?

---

"compilerOptions": ["-t ES5", "--out myoutput.js", "--noImplicitAny"]

This seems a little odd - it's like we're getting closer to the actual structure of ts.CompilerOptions, but we're still expecting something we have to parse. Why not just permit the full command line string or a plain object? For instance, the following could be equivalent:

"compilerOptions": { "target": "ES5", "out": "myoutput.js", "noImplicitAny": true }

and if we really don't want users to have to a type the whole word, the following could be allowed as well:

"compilerOptions": { "t": "ES5", "out": "myoutput.js", "noImplicitAny": true }

---

Should the tsconfig file have a .json extension to indicate intended content, and allow editors to correctly colorize it, format it, etc.?

Yes. In fact, I don't think it should be a .tsconfig file, I think it should be something like tsconfig.json. Dot prefixes for filenames are an accident of history, and now an artifact from indicating hidden files on Unix systems when filesystems didn't support a 'hidden' attribute. Let's just be explicit.

---

[Arnavion]

Should the tsconfig file have a .json extension to indicate intended content, and allow editors to correctly colorize it, format it, etc.?

Yes. In fact, I don't think it should be a .tsconfig file, I think it should be something like tsconfig.json.

Some tools like jake allow both Jakefile and Jakefile.js for the "default file". Perhaps both .tsconfig and tsconfig.json could be allowed here.

Dot prefixes for filenames are an accident of history, and now an artifact from indicating hidden files on Unix systems when filesystems didn't support a 'hidden' attribute.

Well they do have the nice property of automatically becoming hidden files, and of being a shell convention rather than a filesystem attribute. Filesystem attributes require support not just from every filesystem the code is going to live on, but also from tooling like version control. git doesn't support them, for example.

[mhegazy]

Are we not going to be able to specify TypeScript files in the config file? Perhaps this is something for down the road instead?

The idea that you do not need to specify anything. all files in your folder are part of the compilation. I can see an "exclude list", but not include.

This seems a little silly - it's like we're getting closer to the actual structure of ts.CompilerOptions, but we're still expecting something we have to parse. Why not just permit the full command line string or a plain object? For instance, the following could be equivalent:

My preference would be to have the actual structure of ts.CompilerOptions. The problem with this is that there are enum values for module and target, and { "module" : 2 } does not look helpful. so since we are doing a translation step anyways, sticking with something standard is simpler, like the accrual command line you would use to build on the command line without the tsconfig file. I would say, compilerOptions should just take a string which is the command line, that would be parsed.

"compilerOptions": "-t ES5 --out myoutput.js --noImplicitAny"

[NoelAbrahams]

@mhegazy, thanks for raising this.

Should the tsconfig file have a .json extension to indicate intended content, and allow editors to correctly colorize it, format it, etc..

My preference is for the file to be called typescript.json. Visual Studio now provides syntax help and colourisation for these files. In addition it's possible to schema-validate the content.

In a VS project context (say .csproj), should .tsconfig be honored, or ignored in favor of the project.

In VS people tend to use the TypeScript settings UI in order to change project settings. Since editing a JSON config file is even easier, I would suspect that the settings in .csproj will get out of date very soon. Something needs to be done about this. We shouldn't permit settings to be specified in two places, because that just introduces another potential source of confusion. In VS compiling a project with settings specified in both .csproj and the proposed typescript.json should result in a compilation error.

I also have an additional suggestion. We should deprecate the _references.ts file and permit references to be specified directly in typescript.config. That way we are not really introducing yet another config file into the mix, but rather replacing an existing one.

[dbaeumer]

@mhegazy, thanks for starting working on this. I have a couple of comments and questions.

Should the tsconfig file have a .json extension to indicate intended content, and allow editors to correctly colorize it, format it, etc

I am in favor of having a .json extension. Alternative names are ts.json or tsc.json

I agree with Arnavion to store the compiler options as a JSON object instead of a string. It eases readability and will ease to manipulate and read the config file from other tools.

I like the approach of finding a config file by walking up the directory structure and then using it. However from the writeup it is unclear to me what happens if the directory containing the picked config file has a subdirectory that has its own config file (e.g. like git where every directory can have its own .gitignore file). Will it first call tsc with the config file of the sub directory and when finished tsc with the config file of the parent directory excluding the files from the sub directory. And what do we do if the parent has two subdirectories with a config file? Do we need to specify a build order then?

And +1 to be able to specify an exclude list in the config file.

[mhegazy]

@dbaeumer you raise a good point. Initially I thought about excluding the sub directories with the tsconfig file in them, but thinking about this seems confusing and not intuitive. building them as well seems to introduce other complications. i wonder if it should be an error to have this sort of nesting of these tsconfig files. would love to get your thoughts on how to handle this.

[mhegazy]

@NoelAbrahams thanks for the feedback, a few comments:

In VS people tend to use the TypeScript settings UI in order to change project settings. Since editing a JSON config file is even easier, I would suspect that the settings in .csproj will get out of date very soon. Something needs to be done about this. We shouldn't permit settings to be specified in two places, because that just introduces another potential source of confusion. In VS compiling a project with settings specified in both .csproj and the proposed typescript.json should result in a compilation error.

I do not have a good solution here either. i agree that it is a problem, but i am not sure if a compilation error is the best path. Consider cases where team members use VS as their main editor, where others use a different editor, making it an error means that the VS folks get to use their project file, and the others can not get tsconfig support. Maybe an MSBuild build-time warning would be more suited to this situation. thoughts?

I also have an additional suggestion. We should deprecate the _references.ts file and permit references to be specified directly in typescript.config. That way we are not really introducing yet another config file into the mix, but rather replacing an existing one.

Two concerns here, we will need to continue supporting _references in VS and MSBuild, so deprecating it does not mean it will disappear. so what we are doing effectively is adding yet another way of doing the something. Though i am not a fan of _references.ts logic or its name, but it seems to solve the problem.
The other concern is that /// are common enough that it is not a foreign concept so it makes it easier to explain to ts developers, instead of adding another pre-processor step along with /// references.

[danquirk]

Consider cases where team members use VS as their main editor, where others use a different editor, making it an error means that the VS folks get to use their project file, and the others can not get tsconfig support.

It seems to me that if you've gotten to the point where your team has a robust enough .tsconfig to serve other editors then VS should also just prefer it and obsolete your project file. You're guaranteed to experience pain if you have 2 distinct 'project files' but the only kind of 'project file' we could guarantee works everywhere is .tsconfig, so that would need to take precedence.

[Peter-Juhasz]

+1 for .json extension with schema. Please do not introduce stupid linux-style namings for Visual Studio developers on Windows.

And yeah, we may need different configurations for different environments. And these configurations should be set/applied at one centralized place in the build process, like now I can manage TypeScript build configuration bound to MSBuild configuration and not separately.

[billti]

+1 on using an object with properties for each switch rather than a string. That way you can have a schema and intellisense to help you author the properties.

I also agree on dropping the "." from the start of the name. Why would you want this file to be hidden on some platforms if it's your project configuration file? Make it a key file in the project root, similar to "package.json" for NPM. I like Daniel's suggestion of "tsconfig.json".

[NoelAbrahams]

@mhegazy

we will need to continue supporting _references in VS and MSBuild, so deprecating it does not mean it will disappear. so what we are doing effectively is adding yet another way of doing the same thing. Though i am not a fan of _references.ts logic or its name, but it seems to solve the problem.

Why would we need to support _references.ts in VS and MSBuild? If we are going to add compiler settings in the tsconfig that means VS and MSBuild would need to read them, right? The references could be read at the same time.

The other concern is that /// are common enough that it is not a foreign concept so it makes it easier to explain to ts developers, instead of adding another pre-processor step along with /// references

The triple slash reference was never popular with users, e.g. #488. People just don't like to add directives within comments.

If we do the following:

{
    "compilerOptions": { "target": "ES5", "out": "myoutput.js", "noImplicitAny": true },
    "linterOptions": {
        "suppressWarnnings": [234, 3363] 
    },
    "references": [
       "../typings/node.d.ts",
       "./bar.ts"
    ]
}

then tooling can be built to add/remove references.

[dbaeumer]

@mhegazy: throwing an error in this scenario might be confusing and non intuitive as well. And I think there is a real use case. For example sub components are typically nested into its parent component.

I see the following possible solutions:

1. we compile the subdirectory by calling tsc with the corresponding config file. If we go down that path then we will need to support 'project dependencies' as well since a tsc call might trigger another tsc call. This might not be as bad as it sounds since through the _references.ts file the builder already has some ordering notation.
2. we ignore these subdirectories and maybe warn about it. If a developer wants to build such a structure then he needs to use another tool (jake, gulp, make, ...) to call tsc with the various config files in the right order.

I am leaning more towards solution 2. Solution 1 might turn the config support into its own build/make system.

And I would like to pass the config file directly to the tsc compiler as well. Something like tsc @mydirectory\tsc.json