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

[fdecampredon]

There has been work for specifying typescript configuration files, see:

• https://github.com/TypeStrong/tsproj
• https://github.com/fdecampredon/brackets-typescript/#configuration

It would be great to have typescript directly support this kind of mechanism, but it would be a good idea in my point of view to be compatible with those files, or at least to achieve feature parity.

Especially, I have not seen anything about multiple compilation target/project in a single file which have proved to be a great feature of those project.

[basarat]

Especially, I have not seen anything about multiple compilation target/project in a single file which have proved to be a great feature of those project.

I think it does solve this problem:

app/
    .tsconfig  // compile with amd, outDir : ../appOut
    a.ts
    b.ts
test/
    .tsconfig // compile with commonjs, outDir: ../testOut
    c,ts // adds a /// <references> to a.ts
    d.ts

I'd rather have this solution than to maintain my own monster : https://github.com/TypeStrong/tsproj#configuration-file-format. I like it 👍 Thanks guys! now users can just do tsc --watch!

[fdecampredon]

@basarat honestly it does not solve all the problems for example with jest, projects look like that :

app/
  foo
    __test__
       a-test.ts
       b-test.ts
    a.ts
    b.ts
  bar
    __test__
      c-test.ts
      d-test.ts
   c.ts
   d.ts

without a globing system and multiple compilation target described in the same file you won't be able to compile test separately, and there is a lot of other case that we could talk about.

Globing and multiple compilation target described in a same file is the way used by pretty much all the build tools, why would typescript go a different way with a file per folder system ?

[basarat]

honestly it does not solve all the problems

I agree.

Globing and multiple compilation target described in a same file is the way used by pretty much all the build tools, why would typescript go a different way with a file per folder system

I agree that this is a bad idea and the team should reconsider

[Arnavion]

@fdecampredon @basarat Are you suggesting to have something like a list of filenames / globs and then have a compiler options dictionary that applies only to that list? And then have multiple of these in the same file that you can put in the root of the project?

Can you give an example what it would like? I'm guessing something like

[
    ["foo/*.ts", "bar/*.ts", {
        /* options for source files */
        "compilerOptions": {
            /* ... */
        }
    }],
    ["foo/__test__/*.ts", "bar/__test__/*.ts", {
        /* options for test files */
        "compilerOptions": {
            /* ... */
        }
    }],
]

[fdecampredon]

Personaly in brackets-typescript I use something similar to grunt :

For a single compilation target

{
    "target": "ES5",
    "module": "AMD",
    "noImplicitAny": true,
    "sources" : [
        "src/declarations/**/*.ts",
        "src/main/**/*.ts"
    ]
}

For multiple:

{
  "target": "ES5",
  "module": "AMD",
  "noImplicitAny": true,
  "projects" : {
      "project1": {
           "sources": [
                "project1/src/**/*.ts"
            ]
       },
       "project2": {
            "sources": [
                    "project2/src/**/*.ts"
             ],
             "target": "es3"
        }
   }
}

but any format is good for me if allows me to have a fine controls on what is a part of the project (glob), and offer a way to describe multiple compilation target.

[dbaeumer]

@fdecampredon: for me the question is whether tsconfig.json is a build system or a configuration for the tsc compiler. From what I read so far and from looking at the pull request #1692 (comment) it looks like the second. The advantage of this is that everyone can still use its preferred build system when building more than one TS component.

[fdecampredon]

@dbaeumer The problem is that if a 'tsconfig.json' is adopted it will become the de facto standard for typescript project build configuration, independently of the original purpose and scope of the feature.
It would kill the competition and I'm not sure it would benefit in anyway the tooling around typescript.

I seriously would prefer that to never land in typescript than having a solution with limited/incomplete features set.

[Arnavion]

@fdecampredon So with your multiple targets example, if I run tsc from the root of the directory (where the project file is), what should happen? The current compiler can only use one set of compiler options per invocation (same as every other language compiler), so it'd have to spawn two tsc instances - one for project1 (default configuration) and one for project2 (default configuration plus override target to ES3).

I agree with @dbaeumer (and Ander's comment in his PR) that this requires changing tsc to be a compiler + build system instead of a compiler, and that it's better left to specialized build tools like grunt or brackets. I think it's fine for the project file to remain a shorthand for the compiler options within a particular directory, and for the compiler to remain a compiler.

[fdecampredon]

@Arnavion since project are named we could simply invoke :

tsc --project project1

[Arnavion]

@fdecampredon You missed my question. What would happen if I ran just tsc at the root?

[fdecampredon]

nothing without a '--project ' option it would simply display help.

[Arnavion]

So it's the same as the current multiple files implementation, except that it's mashed together into one big file? I guess it allows inheritance of common compiler options, but otherwise it seems to have no benefit. If anything, it means large projects or group of projects belonging to more than one team will always require editing a single file even for the most nested project.

If inheritance of compiler options is the only reason for the single-file approach, I think we can add it to the current multiple-file approach as well using some kind of import feature. That is how other build systems (cmake, autotools, etc.) also work.

[basarat]

If inheritance of compiler options is the only reason for the single-file approach,

No. This is also to have a way of specifying single file -> multiple compile targets.

[johnnyreilly]

If a .tsconfig file exists in the project root then the .csproj is ignored altogether.

+1 to that.

[DickvdBrink]

In my opinion, if you want to use the csproj open that one and if you want the tsconfig solution, just open a .ts file and it will start using the .tsconfig file if it is in the same or parent directory (at least if I understood this correctly).

[basarat]

My strongest opinion is "make it easier to use tsconfig from VS project properties".

A checkbox like "use tsconfig.json to track TypeScript project properties" would be awesome.

[NoelAbrahams]

@DickvdBrink,

I don't think we can do away with .csproj. When there are multiple projects how would we include them in a Visual Studio solution? We could have one project and simply list the rest as folders, but the project infrastructure provides a number of useful features like

• Right-click on a project and build that project. (One can do that on a folder, but the build action will only build project files in that folder - I believe).
• Context sensitive add/remove files.
• Add inter project dependencies.
• Run pre-build/post-build tasks.
• Functionality provided by NTVS project types (npm UI, right-click debug web service...)

This kind of usability is indispensable within Visual Studio.

[NoelAbrahams]

I've opened a couple of feature requests #2180 #2181.

If those features are implemented then we would not need to use .tsconfig - for our use-case in Visual Studio.

[basarat]

Just FYI (you might already know) I found that you can create a .something file on windows explorer by actually creating a .something. file : http://www.basarat.com/2015/03/create-gitignore-file-on-windows.html ❤️

[ToddThomson]

It seems that this feature does not play well with typescript compiler gulp plugins. It looks like a vinyl adaptor for the tsconfig.json project file will be needed to provide the src stream.

[luboid]

Can I use it with VS Web Site, if not is there any plans for implemtation

[mhegazy]

@luboid this is already in the works; tsconfig in vs should be available in the next release.

[asgerhallas]

@mhegazy is that 1.5.2? Or later? Can't seem to find any issue describing this change.

:)

[mhegazy]

@asgerhallas this is in 1.5-alpha and 1.5-beta and should be in 1.5.2 as well.

[asgerhallas]

@mhegazy I might have misunderstood the meaning of VS support then. When I include a tsconfig.json in my project, I thought it would take precedence over the VS-project settings. But compiling from within VS seems to ignore the tsconfig file (compiling from command line works fine). Is that the intent, or am I missing something?

[luboid]

@mhegazy I have also problem with understand how it works, I have create repo with my try

https://github.com/luboid/vs-typescript-website

I am using VS 2015 Community with https://visualstudiogallery.msdn.microsoft.com/3e5ba71c-abea-4d00-b81b-a62de3ad3d53

https://github.com/luboid/vs-typescript-website/tree/master/TypeScript

this is what contains

C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\CommonExtensions\Microsoft\TypeScript

when I save file changes nothing happen, I need to go to Tools -> Options -> Text Editor - TypeScript -> Project to enable "Automatically coompile ..." and JS file is generated but noting else, no map, no d.ts

I give it try with VS 2013 Community but with no success

[mhegazy]

@asgerhallas and @luboid VS currently does not look at tsconfig.json. so weather you have the file in the directory or not, nothing changes. it still behaves as if you are calling builds passing all files on the commandline. the support should be added in the next public release of VS2015.

The reason is the TypeScript VS plugin in ships with VS releases, and VS has a ship scheduled that we, the TypeScript team, have no control over, and it has longer stabilization periods, which leads to some features shipping out of sync.

[asgerhallas]

@mhegazy ah, I see. Thanks for the explanation, I'll await next VS release then :)

[matthew-dean]

Is there any way to merge the efforts of various compilers, transpilers, and other command-line engines into adopting a single config.json format, somewhat like package.json?

Other libraries like Less have had a similar discussion. less/less.js#1893 Why don't all of our communities collaborate and come up with one format? That way we don't litter the root directories of projects with a different config file for every type of transpiled / precompiled / pre- or post-processed language?

[andrewvarga]

Now that there's a config file for the compiler, would it be possible to squeeze this feature in it somehow, which would be immensely useful:
#293

[mhegazy]

@andrewvarga i believe this should be covered by #2338, we need a new mapping format to map an import name to a path.

[andrewvarga]

@mhegazy Nice, I didn't catch that issue. Would that work for /// type of references too ?

[mhegazy]

@andrewvarga this is only for modules as it follows the same runtime resolution process based on your module system (i.e. amd/commonjs). we could not come up with a meaningful /// reference resolution analogy.

[mikemorton]

"the support should be added in the next public release of VS2015."

Is there any word on if this has been officially added? If so, which version number should I be looking for?

[mhegazy]

@mikemorton VS2015 has tsconfig support built in. here is how you get VS2015: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx

[Bobris]

I don't understand how to open tsconfig.json as solution in Visual Studio. Or what type of project I need to use for example if developing node.js application/module (and I don't want to duplicate list of ts files in csproj)...
In Atom-Typescript this not problem just open directory with tsconfig.json and everything magically works.

[mhegazy]

@Bobris, tsconfig does not work in a project. the project file with its configuration (accessible through project properties) is considered the source of truth in a project context.
if you want to use tsconfig, just close your project, and open the file in VS, it will walk up and find the tsconfig that matches it, and will load all files referenced by your tsconfig, just like you would do with Atom, sublime, code, etc..

[Bobris]

@mhegazy Yes, works, need to try for longer time. Now what is left to implement is support for "filesGlob".

[SetTrend]

Does VS 2015 honour to have more than one single tsconfig file so we can have one config for a JS library project and another for the test files in the same .proj? See #4729.

[mhegazy]

@SetTrend, this is tracked by #4714

[SetTrend]

@mhegazy : Excellent 👍