Do I have to reference TypeScript definition in every file?

What I've learned so far is that /// < reference >-ing a module with reference comments is not a good method.

For example: in case you have a file Foo and a file Bar. Both files use jquery, but only file Foo has a reference comment to jquery. If file Foo is deleted for some reason, your file Bar is broken, because the reference is missing.

If you are using TypeScript >= 2.0 It is better to define the TypeScript definition files (.d.ts) in your tsconfig.json under the "files" section.

This could look like this:

{
  "compileOnSave": true,
  "compilerOptions": {
    "noImplicitAny": true,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5", 
    "outDir": "./Scripts/"
  },
  "files": [
    "./src/foo.ts",
    "./src/bar.ts",
    "./Scripts/typings/jquery/jquery.d.ts",
    "./Scripts/typings/jqueryui/jqueryui.d.ts",
    "./Scripts/MicrosoftMaps/Microsoft.Maps.d.ts"
  ]
}

Using the /// directive (reference comments) is often used in examples to get you started quickly, but it is not a best practice. Also many examples come from a version < TypeScript 2.0.

When using TypeScript's internal module system, you can avoid having any <reference> tags at all in the code. I personally do this because I don't want to encode paths (realtive or absolute) within the code as I constantly move stuff around.

One way to do this is by making sure all required declaration files and TypeScript source files are passed to the compiler as arguments during compile time.

Using gulp together with gulp-typescript simplifies this task. You can set noExternalResolve in gulp-typescript to true, and create gulp tasks that take all your .d.ts files along with your sources and pipe it down to the compiler. When you pull in tsd into your stack, you only need to pass the tsd.d.tsfile that contains references to all other definition files installed via tsd.

UPDATE for TypeScript >= v1.5: you can use a tsconfig.json file, and the compiler will get the ordering of the classes right. This removes the need to use gulp-typescript alltogether. You can either chose to have all files explicitly listed in the tsconfig.json file, or completely leave out the files property to include all *.ts/*.tsx files within the directory the tsconfig.json resides (including all subfolders).

A sample tsconfig.jsonmay look like:

{
    "compilerOptions": {
        "target": "ES5",
        "module": "commonjs",
        "lib": [ "es5", "es2015.promise", "dom" ]
    },
    "include": [
        "src/**/*.ts"
    ]
}