(docs) getting started: npm packages installed locally

Author: wardbell

public/docs/_examples/gettingstarted/ts/package.json

@@ -4,6 +4,10 @@
   "description": "",
   "main": "index.js",
   "scripts": {
+    "postinstall": "npm run tsd",
+    "tsd": "tsd link --config src/tsd.json && tsd reinstall -ro --config src/tsd.json",
+    "tsc": "tsc -p src -w",
+    "start": "live-server --open=src",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],
@@ -12,5 +16,10 @@
   "dependencies": {
     "angular2": "2.0.0-alpha.38",
     "systemjs": "0.19.2"
+  },
+  "devDependencies": {
+    "live-server": "^0.8.1",
+    "tsd": "^0.6.5",
+    "typescript": "^1.6.2"
   }
 }

public/docs/ts/latest/guide/gettingStarted.jade

@@ -41,7 +41,7 @@ include ../../../../_includes/_util-fns
 
   :markdown
     We've just defined an Angular 2 **component**,
-    one of the most important beasts in the Angular zoo.
+    one of the most important Angular 2 features.
     Components are our primary means of creating application views
     and supporting them with application logic.
 
@@ -231,71 +231,51 @@ include ../../../../_includes/_util-fns
 .l-main-section
 
   :markdown
-    ## Install tools and application packages
+    ## Install npm packages locally
 
-    We'll need a set of tools for our application development throughout this guide.
-    We've already installed **`live-server`**. Let's install two more:
-
-    - the **TypeScript compiler**
+    We'll replace the web-based scripts in our `index.html` with
+    scripts resident on our local machine.
+    We get those scripts by installing two runtime `npm` packages into our project.
 
+    >**angular.js** - the Angular 2 library.
 
-    - the [**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager") so we can access
-    [TypeScript type definition files](http://definitelytyped.org/ "Definitely Typed").
+    >**system.js** - an open-source library that provides module loading.
 
-    **Open** a terminal window and issue the following `npm` command to install both packages globally:
+    We'll also install three development tools:
 
-  pre.prettyprint.lang-bash
-    code npm install -g typescript tsd
+    >**typescript** - the TypeScript compiler
 
-  .l-sub-section
-    :markdown
-      Now might be a good time to ensure that we're installing Angular-compatible versions of our tools.
-      Issue the following commands in that same terminal window to confirm that we have the appropriate versions:
-    table
-      tr
-        th Command
-        th Versions
-      tr
-        td
-          code node -v
-        td 0.10.* - 0.12.*   &nbsp&nbspBut not 4.0.0 !!!
-      tr
-        td
-          code npm -v
-        td 2.11+  (3.* is fine)
-      tr
-        td
-          code tsc -v
-        td 1.6+
-      tr
-        td
-          code tsd --version
-        td 0.6.5+
-      tr
-        td
-          code live-server -v
-        td 0.8+
-
-  :markdown
-    ### Install local packages
-
-    We'll replace the web-based scripts in our `index.html` with
-    scripts resident on our local machine. We get those scripts by installing two `npm` packages into our project.
+    >**tsd** - the [tsd package manager](https://www.npmjs.com/package/tsd "TSD Package Manager") so we can access
+    [TypeScript type definition files](http://definitelytyped.org/ "Definitely Typed")
 
-    >***angular.js***, the Angular 2 library.
+    >**[live-server](https://www.npmjs.com/package/live-server "Live-server")** - the static file server that reloads the browser when files change.
+    We may have loaded it earlier. We're doing it again
+    locally in our project so we are no longer vulnerable to
+    a global uninstall or version change.
 
-    >***system.js***,  an open-source library that provides module loading.
+    **Open** a terminal window at our application's **root folder**
 
-    In a terminal window at our application's **root folder** type:
+    Enter these commands:
     ```
     npm init -y
     npm i [email protected] [email protected] --save --save-exact
+    npm i typescript tsd live-server --save-dev
     ```
 
     These commands both *install* the packages and *create* an npm `package.json` that will
     help us develop and maintain our application in future.
     The essence of our `package.json` should look like this:
-  +makeJson('gettingstarted/ts/package.json', { paths: 'name, version, dependencies '})
+
+  +makeJson('gettingstarted/ts/package.json', { paths: 'name, version, dependencies, devDependencies'})
+
+  :markdown
+    There is also a `scripts` section. **Find and replace** it with the following:
+
+  +makeJson('gettingstarted/ts/package.json', { paths: 'scripts'})
+
+  :markdown
+    We've just extended our project world with script commands
+    that we'll be running very soon.
 
 .l-main-section
   :markdown
@@ -354,14 +334,15 @@ include ../../../../_includes/_util-fns
     that holds links to the type definition files in those packages.
 
     In the ***root* folder** enter the following command
+    (one of the `npm` scripts we added a short while ago)
 
   pre.prettyprint.lang-bash
-    code tsd link --config src/tsd.json
+    code npm run tsd
 
   :markdown
     That produces a new **`src/typings`** folder with the **`tsd.d.ts`** file.
 
-    Now Angular type checking and intellisense lights up automatically as we write our app
+    Now type-checking and intellisense light up automatically as we write our app
     in the Visual Studio Code and Web Storm editors. Check your editor's documentation for
     instructions on using the `tsd.d.ts` file.
 
@@ -393,49 +374,56 @@ include ../../../../_includes/_util-fns
   :markdown
     ## Compile the TypeScript to JavaScript
 
-    We are no longer transpiling TypeScript to JavaScript in the browser.
-    We're compiling it on our machine instead.
+    We no longer transpile TypeScript to JavaScript in the browser.
+    We run the **T**ype**S**cript **C**ompiler (TSC) on our machine instead.
 
-    Open a terminal window in the **root of the application folder** (not *src*) and enter:
+    Open a terminal window in the **root of the application folder** and enter:
 
   pre.prettyprint.lang-bash
-    code tsc -p src -w
+    code npm run tsc
 
   :markdown
-    After it runs we should find the generated *app.js* file in the *src* folder and also an *app.map.js* file that
+    When it's done we should find the generated *app.js* file in the *src* folder and also an *app.map.js* file that
     helps debuggers navigate between the JavaScript and the TypeScript source.
 
-    We gave *tsc* the watch option (`-w`). It will watch for changes to our *.ts* files and
-    recompile them automatically. Leave it running in this terminal window.
+    Our script set the compiler watch option (`-w`) so the
+    compiler stays alive when it's finished.
+    It watches for changes to our **`.ts`** files
+    and recompiles them automatically.
+
+    Leave this command running in the terminal window.
+    You can stop it anytime with `Ctrl-C`.
 
 .l-main-section
   :markdown
     ## Run the app!
 
-    Now we are ready to see this app in action.
+    Now we are ready to see our app in action.
 
-    Open another terminal window in the **root of the application folder** (not *src*) and
-    launch `live-server` again although this time we add command line
-    arguments telling it to **serve from the application's new location in `src`**:
+    Open another terminal window in the **root of the application folder** and
+    launch `live-server` again although this time we'll do it with
+    one of our `npm` script commands:
 
   pre.prettyprint.lang-bash
-    code live-server --open=src
+    code npm start
 
   :markdown
-    **live-server** loads the browser for us, serves the HTML and JavaScript files, and we should see it display our
-    application message once more:
+    **live-server** loads the browser for us, serves the HTML and JavaScript files,
+    and displays our application message once more:
 
   figure.image-display
     img(src='/resources/images/devguide/getting-started/my-first-app.png' alt="Output of getting started app")
 
   :markdown
     ### Make some changes
-    **live-server** detects changes to our files and refreshes the browser page for us automatically.
+    **`live-server`** detects changes to our files and refreshes the browser page for us automatically.
 
     Try changing the message to "My SECOND Angular 2 app".
 
-    The TypeScript compiler running in the first terminal window is watching our source code. It recompiles and produces
-    the revised *app.js*.  The *live-server* sees that change and reloads the browser.
+    The TypeScript compiler in the first terminal window is watching our source code. It recompiles and produces
+    the revised *app.js*.  The `live-server` sees that change and reloads the browser.
+
+    Keep `live-server` running in this terminal window. You can stop it anytime with `Ctrl-C`.
 
 .l-main-section
   :markdown