About true-composite projects support

[timocov]

Just a note about what this issue means exactly (at least from my current understanding) and some thoughts.

First of all, having this issue opened doesn't mean that the tool doesn't support composite projects. Please keep reading (see "workaround" section below).

Technical details

About the issue

If you have a composite project, it means that most likely you have some sort of a "solution" config that references other projects that might reference other projects and so on. The tool doesn't work with projects but with files instead, so it doesn't care about projects and their relationship. It doesn't even load files based on files, include and exclude options in tsconfig (as it is mainly a directive for tsc cli). But what it does care about is the compiler options. If your compiler options are consistent across projects within a composite projects, then you should be fine even if you have composite: true in there (yeah you might see a warning but the tool can just work well). The issue started when your "default" tsconfig doesn't have any compiler options but just references to other projects (for example like this). In this case the tool will not load any compiler options your project is using to get compiled and you might experience "strange" behavior like compilation errors while running tsc -b "just works fine".

Even if your compiler options are a touch different, it still might work well, it really depends on many factors and actual differences. E.g. in you have differences in target option it shouldn't affect anything, but different stripInternal can and probably will.

Compiler API for composite projects

Another note I'd like to cover here is another reason why it still not implemented (and probably cannot be? feel free to share your thoughts). If you want to compile a composite project (in a build mode), the compiler provides different set of API. Instead of using ts.createProgram you have to use ts.createSolutionBuilder API. This API looks like a high-level API to perform compilation in a similar way tsc does, but it doesn't provide you anything about the program it is going to build. It is a high-level API to perform actions like "compile project", "clean project", "build references" and so on. The API doesn't provide a program instance (and a type checker) for each sub-project unless they are "invalidated". In fact, it might not even write any output for a project (if it decides that nothing has changed since "last" build).

Another question/issue that needs to be solved here is detecting where the input file belongs to (which sub-project) and compile only projects its project depends on. And probably it will cause other questions and I don't see yet.

P.S.: If there are other cases that aren't aligned with the explanation above - feel free to share them here. I'll be happy to update this post to include additional cases.

Workaround

The best and simplest solution I can suggest is to create a separate tsconfig file with all your compiler options and pass them to the tool via either --project CLI option or compilationOptions.preferredConfigPath option in the config file (depends on what you use). To avoid duplication, you can then extend other tsconfig files with that newly created "options" tsconfig so you won't repeat the same options again and again across your project (I hope you're doing this already anyway).

It is super simple and requires almost no effort (this is one of the main reasons why there is no support for this feature yet..

About creating tsconfig for the tool

Here is the list of tips you can apply that might make your life easier.

1. If the compiler options across projects aren't the same, the safest options would be to includes the most common options in that new tsconfig and probably use it for the tool only. If these different options are conflicting (e.g. different lib options or different stripInternal value), the best solution would be to compile different projects via build mode prior bundling typings, and then tell the tool to bundle typings with input files being d.ts outputs from previous step. In this case you can keep different compiler options while building a project and bundle typings (and it should work somewhat quicker as the tool doesn't need to compile the full version of the project).

2. These options shouldn't necessary include all of the options, but these that you do care in terms of declaration generation and ones that your project can be compiled with. If you're running the tool against d.ts files only, then probably almost any tsconfig would work as no compiler options will affect output, it just should be compile-able. But this is advanced and make sure you understand what you're doing - the safer option is to include compiler options you use to compile the project.

Conclusion

I admit that it might be possible to write a ton of code to make it work with true-composite projects, but I just cannot justify it comparing to creating a new tsconfig file for dts bundling.

If you have any ideas/thoughts on this topic, feel free to share it here. If you have issues that you're experiencing with bundling composite projects - feel free to ping me and I will try to assist you.

[igorpupkinable]

@timocov RE: #93 (comment)

I left the company, but I still have repository https://github.com/igorpupkinable/dts-bundle-generator-issues-50

Would you like me to update this repo so the issue is reproducible?

[timocov]

If you have time and can do that - it would be much appreciated!