Installation and setting up your environment

There are many ways to set up your environment and a wide range of tools that you can use. I have chosen what I think is the simplest setup (this is a very subjective opinion). So the set is to use:

Package manager and runtime: Node
Compiler: Typescript
Orchestrate the building and packaging of application code: Webpack

You can imagine a similar setups for example you can use Node, Babel and Grunt as an equivalent set up.

Even though this may look complicated, I hope that as you work through this you will not find it too hard. In all I could imagine this being simpler and there will soon be scripts that can automate all of this for you. If you follow these instructions and run into any problems please let me know.

Installing Node and npm

If you are going to be using node extensively then it is better that you install the nvm application, which will allow you to install node and target specific versions etc.

On Linux

To do this on Linux, we will install the c++ complier and build tools for Linux

sudo apt-get update
sudo apt-get install build-essential libssl-dev

Now we can install nvm:

https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh

Then we use nvm to install node with:

nvm install 6.0

As you can see you can target a specific version of node that you want to install.

You can check the installs worked correctly wtih:

node -v
command -v nvm

Typescript and webpack

Now we will look at installing TypeScript and set up a development environment with Node. We will be using webpack for transpiling typescript and for bundling. We will also set up webpack-dev-server to enable hot loading - so you can view changes to your application as you are coding without having to refresh your browser.

First create a folder for you application and run npm init, follow the prompts to create a basic package.json file for your application.

npm init

Install webpack and webpack dev server

Install webpack globally and then you can link it to your application. This will save some space, however you can also just install everything locally to your application if space is not of concern.

npm install -g webpack

For hot loading install the webpack-dev-server

$npm install webpack webpack-dev-server -g

Install additional loaders as required:

$npm install css-loader style-loader -g

Then you run the server with:

webpack-dev-server --progress --colors

Okay now, we ned to get typescript installed.

$npm install typescript -g

This will install typescript globally.

For each project you need to run:

npm link typescript

which will link the global installs with the project. As I mentioned earlier, if you want to install everything locally then you can leave out the -g in the commands above.

Now in order to use JavaScript we need the type definitions for these libraries. We will use the newly introduced @types mechanism. For example this will install the TypeScript type definitions for jQuery in your project and update your package.son to reflect this dependency (because of --save)

npm install --save @types/jquery

Equivalently you can use the tsd and typings mechanism to do this. But since @types is probably the way to do this going forward I just used that.

Okay, now your global environment is almost complete. Now let us get our project running.

To set up a new project

Create a directory for the project and cd into that that directory then run:

$ npm init

Installing React and React Dom

To intall React and React-dom and the relevant type dfinitions you can run

npm install react react-dom -g
npm link react react-dom --save

npm install @types/react @types/react-dom --save -dev

Installing other JavsScript libraries

Also you need to run to intall the typings for any javascript libraries you need like jquery.

$ npm link --save jquery
$ npm install --save @types/jquery

To install a javascript library like lodash which I like to use for functional programming in JavaScript you can run:

  npm install -g lodash 
  npm link lodash
  npm install @types/lodash --save -dev

Then you need to import the library to use it in your TypeScript code which you can do as:

import * as  _ from 'lodash';

Setting up your tsconfig.son and webpack.config.js

Then you need to set up

tsconfig.json

{
    "compilerOptions": {
        "sourceMap": true,
        "noImplicitAny": false,
        "module": "commonjs",
        "target": "es5",
        "jsx": "react"
    },
    "include": [
        "./**/*"
    ],
        "exclude": [
      "node_modules/*"
    ]
}

webpack.config.js

module.exports = {
    entry: "./index.tsx",
    output: {
        filename: "bundle.js"
    },

    // Enable sourcemaps for debugging webpack's output.
    devtool: "source-map",
    resolve: {
        // Add '.ts' and '.tsx' as resolvable extensions.
        extensions: ["", ".webpack.js", ".web.js", ".ts", ".tsx", ".js"]
    },

    module: {
        loaders: [
            // All files with a '.ts' or '.tsx' extension will be handled by 'awesome-typescript-loader'.
            { test: /\.tsx?$/, loader: "ts-loader" }
        ],

        preLoaders: [
            // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.
            { test: /\.js$/, loader: "source-map-loader" }
        ]
    },

    // When importing a module whose path matches one of the following, just
    // assume a corresponding global variable exists and use that instead.
    // This is important because it allows us to avoid bundling all of our
    // dependencies, which allows browsers to cache those libraries between builds.
    externals: {
        "react": "React",
        "react-dom": "ReactDOM",
        "d3":d3
    },
};

You need to install and link any loaders that you have specified in your webpack config webpack.config.js

 npm link ts-loader --save -dev

The instructions on the Typescript website which are very good use awesome-typescript-loader that I had some trouble with. So I switched to using ts-loader instead.

In your project you will need an index.html and index.tsx (or index.ts which you have specified as an entry point in your tsconfig.json)

Then you are good to go. Just run the server with:

$ webpack-dev-server --progress --colors

If you are using bootstrap then you have to install bootstrap. I install them globally and then link them using:

npm install bootstrap -g
npm link bootstrap --save

The path to your external bootstrap dependencies has to be entered in your html file. in this example we are using React and Bootstrap.

<head>
<link href="./node_modules/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
 <!-- Dependencies -->
        <script src="./node_modules/jquery/dist/jquery.js"></script>
        <script src="./node_modules/bootstrap/dist/js/bootstrap.min.js"></script>
        <!-- External JavaScript Dependencies -->
        <script src="./node_modules/jquery/dist/jquery.js"></script>
        <script src="./node_modules/bootstrap/dist/js/bootstrap.min.js"></script>
        <!-- if you need React -->
        <script src="./node_modules/react/dist/react.js"></script>
        <script src="./node_modules/react-dom/dist/react-dom.js"></script>
        <!-- Main transpiled typescript-->
        <script src="bundle.js"></script>
</body>

Installation and setting up a project