Update README.md to include example of using triple-slash directive.

[cookrn]

These directives are used to instruct the compiler of various types of dependencies between files that are not otherwise obvious. By leveraging them in our code, we can manage type definitions for untyped third-party JS libraries without making our project configurations more complex.

I struggled for a solid day to first understand that it was ts-node that was unable to locate my module type definitions and then to configure my project so that it could find them when needed. Hopefully this example might save others some time!

[coveralls]

Coverage remained the same at 86.082% when pulling 0efead5 on cookrn:patch-1 into 2609663 on TypeStrong:master.

[coveralls]

Coverage remained the same at 86.082% when pulling 0efead5 on cookrn:patch-1 into 2609663 on TypeStrong:master.

[coveralls]

Coverage remained the same at 86.082% when pulling 0efead5 on cookrn:patch-1 into 2609663 on TypeStrong:master.

[coveralls]

Coverage remained the same at 86.082% when pulling 78d2c69 on cookrn:patch-1 into 2609663 on TypeStrong:master.

[blakeembrey]

@cookrn Is there a reason you couldn't use the typeRoots feature? It seems a bit easier to me, though I am happy to include documentation on the triple-slash reference feature too.

[cookrn]

@blakeembrey great question. Basically, I was scared off by this note in docs:

If typeRoots is specified, only packages under typeRoots will be included.

We use lots of definitions from DefinitelyTyped, some libraries that include their own types, and also ad-hoc definitions in our project for untyped JS libraries. Wouldn't we lose libraries that specify their own types if we used typeRoots unless we manually added each to the list?

[blakeembrey]

@cookrn Sounds like an opportunity to fix that description too! So typeRoots is for "global" definitions, and yes, it will stop working unless you add in node_modules/@types - this is where DefinitelyTyped gets installed to so it will keep working if asked. The other way packages get discovered, when written using module system (e.g. import and export) is via path - this is also implicitly node_modules/@types.

[blakeembrey]

Specifically:

Keep in mind that automatic inclusion is only important if you’re using files with global declarations (as opposed to files declared as modules). If you use an import "foo" statement, for instance, TypeScript may still look through node_modules & node_modules/@types folders to find the foo package.

[cookrn]

Thanks for the info @blakeembrey. I'm not following if you're hoping I can make additional changes in this PR or it should be closed? Maybe you mean the quote from the TypeScript docs could be added to the typeRoots section of this README?

[blakeembrey]

@cookrn Sorry, I thought the quote you used was from the README before I realized it's from TypeScript and quoted the part below it that mentions your concern. I'm happy to merge this, just don't think people should need it normally if they want to use typeRoots or paths. Is anything about those two features in the README confusing enough that you think /// is the best path to documenting or should we just make a note/link to it documented elsewhere?

[cookrn]

@blakeembrey since the other options are preferred, what if I slim down the diff here to mention triple-slash directives as an alternative option rather than a scenario that may be required depending on your configs. Now that I understand typeRoots I understand why they would've worked, but maybe helpful to still mention triple-slash. Something shorter like If you prefer to....., you may also use.... with a link?

[blakeembrey]

@cookrn Absolutely, would love to accept whatever you feel works with 1. the preferred way in TypeScript, and 2. the best way to document how to accomplish what you need 👍

[cookrn]

@blakeembrey I reduced the language a bit to still link to the official docs and call them out as an alternative. Look ok?