Hey there, after digging about how Typescript settings mesh together, I decided to write my article about what I found the hard way, hoping to clear the path for newcomers.
Once you install Typescript, default values are a bit dumb. For example, 99% of the world would put the source code in a
src directory, and typescript has to be configured explicitly this way. Let's see my
This is part of my setup. I will go through some of these options so you can choose wisely.
The "target" option
Possible values are:
If you leave it blank, or choose
You may think this is a great default value and be tempted to use
Promise, and typescript will let you use them, BUT typescript will not add any polyfill to your code. Beware of this!
Similarly you can choose to run several different options,
ES5 (if your users are on Internet Explorer),
ES6... I prefer
esnext to be able to use the latest features of the language and leave to Babel the transpilation step.
Did you know that prior to ES6 there was no official way to import some JS code inside another JS code? The community came out with several options and the next section will discuss them.
The "module" option
module determines the way modules (and files) express dependencies between each other. Possible values are:
If you use None you cannot use
AMD, System and CommonJS are (IMHO) a thing of the past. the first (AMD) came from RequireJS and the second from SystemJS. These two are browser's solutions. Not so long ago there was no way to express dependencies across JS files, so many competing systems came out to solve the same problem. AMD and SystemJS did not get enough fortune to become a standard.
CommonJS is a spec that is very similar to what NodeJS has implemented (
UMD stands for Universal Module Definition and tries to deliver a module that works with every possible module definition defined before.
However, the ECMAScript community went for the
import/export solution, and node has embraced that too, and we have that available in
Again, I prefer to use Typescript as a superset of JS, so I choose
esnext and let webpack decide how to bundle stuff together.
outDir or outFile ?
You have decided which module system you want to use (you know my vote for
ES6), but do you want a single file in output (
outFile) or many single files in a output directory (
If you write JS for the browser you may be tempted to go for
outFile and let TS deal with everything. You may think that this way you can skip webpack, babel and so on. The problem is that TS allows to use this option only with
system. So this is a hard requirement for that.
The second big problem is that, to build a single file with all modules, Typescript needs also to know the order of files, so you have to provide the list in the right order. Imagine having 30-50-100 modules...
Again, my advice is to use
outDir. For every source file you get a compiled file in the output directory. Then, again, did I tell you of webpack + babel?
This setting accepts two possible values:
classic. At this point there's no need to have a value different than
node here. For what I read in the official documentation,
Nowadays, this strategy [
classic] is mainly present for backward compatibility.
Since we are working in the browser and we are targeting a JS version greater than ES2015, I use the defaults that are
DOM,ES6,DOM.Iterable,ScriptHost. The list of all available libraries is here. If you forget to put those, Typescript will output weird errors like missing
Set interface or other stuff - I guess the problem is that TS goes in
node_modules and finds code that is obviously thought for Node, and it fails somehow.
An option for IDEs to trigger compilation on a file save. If your IDE does not support it you can disable it but having it turned on it does not harm.
You use Typescript because you want it to catch syntax errors in your library. However, the default value for this option is
false and this means that many syntax checks are not done for you.
If you start a new project, I strongly advise to turn on this option. If you, like me, are converting a JS library to TS, this option may transform your job in hell: introduce it gradually and slowly.
So many choices to do and I guess inexperienced developers do not know what to do at first. Hoping to do them a favour!
I've also cited Webpack + Babel setup here, and this will be discussed in another article. It will require some changes here and there, and typescript will only be used to check the syntax of the project, but the transpilation will be done by Babel.
Curious? Stay tuned!