docs(guides): rework typescript guide (#1530)

Rework and synchronize the TypeScript guide with the
others (see #1258). It now stems from _Getting Started_.

Author: mtrivera

src/content/guides/typescript.md

@@ -7,25 +7,36 @@ contributors:
   - mtrivera
 ---
 
+T> This guide stems from the [*Getting Started*](/guides/getting-started/) guide.
+
 [TypeScript](https://www.typescriptlang.org) is a typed superset of JavaScript that compiles to plain JavaScript. In this guide we will learn how to integrate TypeScript with webpack.
 
 
 ## Basic Setup
 
-In order to get started with webpack and TypeScript, first we must [install webpack](/guides/installation/) in our project.
-
-To start using webpack with TypeScript you need a couple of things:
-
-1. Install the TypeScript compiler in your project.
-2. Install a TypeScript loader (in this case we're using `ts-loader`).
-3. Create a __tsconfig.json__ file to contain our TypeScript compilation configuration.
-4. Create __webpack.config.js__ to contain our webpack configuration.
+First install the TypeScript compiler and loader by running:
 
-You can install the TypeScript compiler and loader by running:
+``` bash
+npm install --save-dev typescript ts-loader
+```
 
- ``` bash
- npm install --save-dev typescript ts-loader
- ```
+Now we'll modify the directory structure & the configuration files:
+
+__project__
+
+``` diff
+  webpack-demo
+  |- package.json
++ |- tsconfig.json
+  |- webpack.config.js
+  |- /dist
+    |- bundle.js
+    |- index.html
+  |- /src
+    |- index.js
++   |- index.ts
+  |- /node_modules
+```
 
 __tsconfig.json__
 
@@ -35,7 +46,6 @@ Let's set up a simple configuration to support JSX and compile TypeScript down t
 {
   "compilerOptions": {
     "outDir": "./dist/",
-    "sourceMap": true,
     "noImplicitAny": true,
     "module": "commonjs",
     "target": "es5",
@@ -47,31 +57,33 @@ Let's set up a simple configuration to support JSX and compile TypeScript down t
 
 See [TypeScript's documentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) to learn more about `tsconfig.json` configuration options.
 
-__webpack.config.js__
-
 To learn more about webpack configuration, see the [configuration concepts](/concepts/configuration/).
 
 Now let's configure webpack to handle TypeScript:
 
-```js
+__webpack.config.js__
+
+``` js
+const path = require('path');
+
 module.exports = {
- entry: './index.ts',
- module: {
-   rules: [
-     {
-       test: /\.tsx?$/,
-       use: 'ts-loader',
-       exclude: /node_modules/
-     }
-   ]
- },
- resolve: {
-   extensions: [".tsx", ".ts", ".js"]
- },
- output: {
-   filename: 'bundle.js',
-   path: __dirname
- }
+  entry: './index.ts',
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        use: 'ts-loader',
+        exclude: /node_modules/
+      }
+    ]
+  },
+  resolve: {
+    extensions: [ ".tsx", ".ts", ".js" ]
+  },
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist')
+  }
 };
 ```
 
@@ -82,28 +94,58 @@ This will direct webpack to _enter_ through `./index.ts`, _load_ all `.ts` and `
 
 [`ts-loader`](https://github.com/TypeStrong/ts-loader)
 
-We will use `ts-loader` in this guide as it makes enabling additional webpack features, such as importing other web assets, a bit easier.
+We use `ts-loader` in this guide as it makes enabling additional webpack features, such as importing other web assets, a bit easier.
 
 
 ## Source Maps
 
-To learn more about Source Maps, see the [development guide](/guides/development.md).
+To learn more about source maps, see the [development guide](/guides/development).
 
-To enable source maps, we must configure TypeScript to output inline source maps to our compiled JavaScript files. The following line must be added to our `tsconfig.json`:
+To enable source maps, we must configure TypeScript to output inline source maps to our compiled JavaScript files. The following line must be added to our TypeScript configuration:
 
-``` json
-"sourceMap": true
+__tsconfig.json__
+
+``` diff
+  {
+    "compilerOptions": {
+      "outDir": "./dist/",
++     "sourceMap": true,
+      "noImplicitAny": true,
+      "module": "commonjs",
+      "target": "es5",
+      "jsx": "react",
+      "allowJs": true
+    }
+  }
 ```
 
 Now we need to tell webpack to extract these source maps and into our final bundle:
 
 __webpack.config.js__
 
-```js
-module.exports = {
- devtool: 'inline-source-map',
- // Remaining configuration...
-};
+``` diff
+  const path = require('path');
+
+  module.exports = {
+    entry: './index.ts',
++   devtool: 'inline-source-map',
+    module: {
+      rules: [
+        {
+          test: /\.tsx?$/,
+          use: 'ts-loader',
+          exclude: /node_modules/
+        }
+      ]
+    },
+    resolve: {
+      extensions: [ ".tsx", ".ts", ".js" ]
+    },
+    output: {
+      filename: 'bundle.js',
+      path: path.resolve(__dirname, 'dist')
+    }
+  };
 ```
 
 See the [devtool documentation](/configuration/devtool/) for more information.
@@ -138,8 +180,8 @@ declare module "*.svg" {
 Here we declare a new module for SVGs by specifying any import that ends in `.svg` and defining the module's `content` as `any`. We could be more explicit about it being a url by defining the type as string. The same concept applies to other assets including CSS, SCSS, JSON and more.
 
 
-## Performance Loader
+## Build Performance
 
-[`awesome-typescript-loader`](https://github.com/s-panferov/awesome-typescript-loader)
+W> This may degrade build performance.
 
-Awesome TypeScript Loader has created a [wonderful explanation](https://github.com/s-panferov/awesome-typescript-loader#differences-between-ts-loader) of the difference between `awesome-typescript-loader` and `ts-loader`. The configuration for `awesome-typescript-loader` is more complex than `ts-loader`.
+See the [Build Performance](guides/build-performance/) guide on build tooling.