Explain how to configure TypeScript for use on Node.js

[jfathman]

TypeScript is a great language for developing server-side applications that run on Node.js, and for developing IoT applications that run on Node.js on embedded devices.

But getting started is difficult due to the complexity of DefinitelyTyped, TSD (deprecated), Typings, triple-slash references versus package.json versus tsconfig.json versus typings.json, typings/main/ambient/node/index.d.ts, etc.

A new page in the TypeScript Handbook under Project Configuration that explains how to configure TypeScript for use on Node.js would be a big help.

[phreed]

I am looking for the same thing.
I expected to find something under Consumption or Production.

The node @typings can be installed with:

  npm install @types/node --save

The expectation being that it should then be possible to import one of the modules defined for node.
e.g.

import http = require('https');

The basic problem is that '@types/node' is a 'multi-module' definition file,
it contains more than one module.
In this case the module required does not have the same name as the package containing it.
We need to supply a little help.
In my experience the following mechanisms provides that bit of help.
It appears that placing a ///reference at the very top of the file can correct the problem.

///<reference path="../../../../node_modules/@types/node/index.d.ts" />

It is my understanding that the same effect can be obtained by adding the reference to the 'tsconfig.json' in the 'files' section (or alternatively in the 'include' section).

"include": [
    "./src/ts/**/*.ts",
    "./node_modules/@types/node/index.d.ts"
],

However this does not appear to be not the proper way.
I believe one of the the following is preferred.

///<reference types="node" />

'tsconfig.json' in the 'files' section (or alternatively in the 'include' section).

"compilerOptions": {
   ...
    "types": [
      "node"
    ],

Can we get some love from the TypeScript team to fact-check my hypothesis?
I also have my own multi-module definition file, I presume what works for 'node' will work for mine as well?

[mhegazy]

have you tried TS 2.0 with the @types packages? see https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/declaration%20files/Consumption.md

[phreed]

@mhegazy
yes, the @types packages are what I am talking about.
There is a weakness in the document https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/declaration%20files/Consumption.md
It does not describe how to consume multi-module packages (like @types/node).
I provided a description of what seems to work and is missing in the comment.
Is the description correct?

[mhegazy]

You should not need to specify typeRoots if your node_modules is on the same level as your tsconfig.json is this the case for you? i would say this is an implementation bug rather than a documentation one.

[phreed]

@mhegazy Right typeRoots is not necessary so I removed it from the comment. But, I think the types is necessary and is not present in the documentation.

[mhegazy]

types is not if the tsconfig.json is next to your node_modules. i have filed a bug to fix the issue (microsoft/TypeScript#10617).

The compiler does "automatic" inclusion to @types packages; it looks under <tsconfig.json directory>\node_modules\@types and includes all files.

i am guessing your node_modules is one or more levels higher than your tsconfig.json, and thus it is not being picked up automatically.

the other option to include it is either 1. add it to the types list, or 2. add a /// <reference types="..." /> to it.

[mhegazy]

i should add that the intention of the design was not to need to add either. and thus the lack of documentation was under the impression that these references should not be needed, and users do not need to be distracted by them.

[phreed]

@mhegazy
It seems like this 'magic' behavior should be explained somewhere other than this issue.
In any case, it is now documented here.

I am also developing .d.ts files for npm packages that I am using for which there is no .d.ts
In that case, should I simply add an entry to typeRoots where my d.ts resides?
In other worlds does the "automatic" inclusion to @types work by looking in all of the typeRoots?

If typeRoots is specified does it replace or add-to the default typeRoots values?

[mhegazy]

It seems like this 'magic' behavior should be explained somewhere other than this issue.
In any case, it is now documented here.

sure thing.

I am also developing .d.ts files for npm packages that I am using for which there is no .d.ts

You should not bundle third-party declarations with your package. these should be published separately.
So for instance you depend on JQuery, and let's say there is no JQuery definition package. so what you should do is publish an @types package for JQuery. to do so, you can push the declaration file to https://github.com/DefinitelyTyped/DefinitelyTyped/tree/types-2.0 and then it would be pushed to npm automatically.
Your package then will add a dependency on @types\JQuery. and in your package declaration file, you would either have an import ... from "JQuery" or /// <reference types="JQuery" />.
The rational here, is having one package per definition causes less version conflicts for end users.

If typeRoots is specified does it replace or add-to the default typeRoots values?

I am not sure what you mean by that. can you elaborate.

[phreed]

...

I am also developing .d.ts files for npm packages that I am using for
which there is no .d.ts

You should not bundle third-party declarations with your package. these
should be published separately.

No, I am not going to bundle the third-party declarations with my package,
but the change-commit-install-fail churn is time consuming and pollutes the
commit history. Once the typings are working for my project then I will
commit it as its own package.

...

If typeRoots is specified does it replace or add-to the default typeRoots
values?

I am not sure what you mean by that. can you elaborate.

Sure.
By default the 'typeRoots' is node_modules/@types as if...

"typeRoots": [ "node_modules/@types" ]

If I want to add another directory, say @types, and I want the compiler to
continue to look in node_modules/@types do I need to make it explicit...

"typeRoots": [ "node_modules/@types", "@types" ]

...or is 'node_modules/@types' implicitly included? ...

"typeRoots": ["@types]

Similarly, can 'node_modules/@types' be ignored by...

"typeRoots": [ ]

No, I have no particular use-case, I am just trying to understand the
semantics.

[phreed]

| The compiler does "automatic" inclusion to @types
https://github.com/types packages; it looks under <tsconfig.json
directory>\node_modules@types and includes all files.

Does the "automatic" inclusion of @types https://github.com/types work by
looking in all of the typeRoots directories?

[mhegazy]

it is explicit. so you need to list "node_moduels\@types" if you want the compiler to look inside it.

Does the "automatic" inclusion of @types https://github.com/types work by
looking in all of the typeRoots directories?

if typeRoots is specified on the command-line or in the tsconfig, the compiler uses it and does not look elsewhere.

for example, here is a sample config for Definitely Typed: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/types-2.0/abs/tsconfig.json

if uses the parent folder as the only typeRoot, and does not look into @types

[phreed]

I think that covers it pretty well, thanks.