[Docs] Explain how Typescript support works

[luisnaranjo733]

I'm testing out madge on my TS RN codebase, and I'm surprised to see that it just magically works without specifying a tsconfig.

For example yarn madge --circular --extensions ts,tsx ./

Although this is cool and exciting, it gives me pause because the documentation doesn't explain how this works. I read the source and followed the path through a series of external npm dependencies. After cloning 4 different repositories, I now kind of understand that TS support is heavily abstracted/delegated away by external modules.

I think it would be helpful if the docs for madge explained how this magic happens at a high level. As a new user, I still don't know if madge is actually using my tsconfig or if it is applying its own TS configuration that also just happens to work (also can someone please clarify how this works? I still don't have the answer to that question).

[Aside] I'm asking about TS specifically, because that is what I'm interested in, but I believe this also applies to other variants that transpile to JS (like Flow for instance).

[luisnaranjo733]

Tagging @mrjoelkemp and @davidfirst for visibility, since they are credited for TS support in the changelog :)

[davidfirst]

As far as I know, it doesn't use the tsconfig. The way how it works is similar to JS files.

I'll try to describe it shortly, I hope I don't miss anything important.

1. parses the files and produces an AST (abstract syntax tree).
2. goes through the AST and finds the import/require statements. (done by precinct package, which uses detectives for the various languages.)
3. finds for the file where that dependency comes from (done by filing-cabinet package, which uses different lookups for various languages).

For example. /src/a.ts => import { something } from './b'; /src/b.ts => export function something {} According to the steps above, when you pass a.ts file, it does the following:

1. parses the a.ts file and generates AST. (search for AST explorer to find how the AST looks like).
2. during the walk on the AST, it finds ImportDeclaration, which is the import statement, and returns the dependency value, which is ./b;
3. since this is a .ts file, it uses typescript package to resolve the dependency. typescript resolves search for ./b and returns the file src/b.ts.

I hope it is clear. If not, please let me know on which part to elaborate.

[luisnaranjo733]

That makes sense, thanks!

Is it possible to add this to the documentation? In my particular use case, it is fine that madge doesn't use my tsconfig (seems to be working fine). But for those who have very custom configs, I don't know if madge will successfully transpile to JS if it doesn't respect the project's defined build system.

[3rdp]

I second that it will be very good to mention that for a mixed javascript+typescript project you might need to do

madge --extensions ts,tsx,js,jsx

for cli to pick up the typecript dependencies as well.

[c-vetter]

Does this require additional documentation or can it be closed?