Search code examples
typescript

When should reference tags be used?


Part of the TypeScript handbook's namespace documentation says (emphasis mine):

Here, we’ll split our Validation namespace across many files. Even though the files are separate, they can each contribute to the same namespace and can be consumed as if they were all defined in one place. Because there are dependencies between files, we’ll add reference tags to tell the compiler about the relationships between the files...

The beginning of the same article has a note implying that it was written long ago, so I'm wondering if modern TypeScript should follow this suggestion.

What are reference tags and when do they need to be used?


Solution

  • What are reference tags?

    See https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-path-

    They make other files and their declarations known to the compiler, like the Validation.StringValidator in the given example.

    … and when do they need to be used?

    In modern TypeScript that is using ES6 module syntax, basically never. Use an import declaration instead.

    They're only useful when working with multiple script files (for <script type="text/javascript">) that share the global scope.