Add the Using npm Packages topic

This adds the topic page, __Using npm Packages__ that organizes
information on installing/using packages found on npm. Part of #76

.gitignore

@@ -1,2 +1,3 @@
 docs/
 node_modules/
+package-lock.json

doc/steal-topics/development/development-bundles.md

@@ -9,11 +9,11 @@ Development bundles enable faster reload times during development by bundling to
 * **dev-bundle**: A bundle that contains all of your *node_modules* dependencies, and the configuration contained within your *package.json*. Use this bundle type if you want the fastest page load times.
 * **deps-bundle**: A bundle that contains all of your *node_modules* dependencies. Unlike the dev_bundle, this *does not* contain your package.json configuration. Use this bundle type if you plan on changing configuration often or are installing new npm dependencies.
 
-# API
+## API
 
 The API for development bundles is split between parts in [steal-tools], where the bundles are created, and [steal], where you configuration the loader to load the bundles.
 
-## steal
+### steal
 
 * [config.depsbundle]: Specifies that a *deps bundle* should be preloaded before the [config.main].
 * [config.devbundle]: Specifies that a *dev bundle* should be preloaded before the [config.main].
@@ -24,7 +24,7 @@ Note that these config values should almost always be specified in the steal scr
 <script src="node_modules/steal/steal.js" deps-bundle></script>
 ```
 
-## steal-tools
+### steal-tools
 
 Creating dev and deps bundles can be done either through the `steal-tools bundle` command, or through `stealTools.bundle()` when using the JavaScript API.
 
@@ -44,7 +44,7 @@ Creating dev and deps bundles can be done either through the `steal-tools bundle
     });
     ```
 
-# Enabling Development Bundles
+## Enabling Development Bundles
 
 > *Note*: The development bundles feature requires at least steal 1.2.0, steal-tools 1.3.0, and steal-less 1.2.0 (if using steal-less).
 

doc/steal-topics/development/using-packages.md

@@ -0,0 +1,84 @@
+@page StealJS.using-npm-packages Using npm Packages
+@parent StealJS.development
+@body
+
+[npm](https://www.npmjs.com/) is a JavaScript package managers that allows you to use and share all types of packages. StealJS supports using npm packages, and it is the recommended way to use Steal in any non-legacy application.
+
+Using npm with StealJS is as easy as *installing steal* with npm:
+
+```shell
+npm install steal --save-dev
+```
+
+> Note, whether you use `--save-dev` or `--save` may depend on how you plan on deploying your application. Most of the time you will not need the [steal] package in production because your application has been build into separate bundles which will contain steal.
+
+Then use steal with a script tag:
+
+```html
+<script src="./node_modules/steal/steal.js"></script>
+```
+
+This will tell steal to load your __package.json__ file, making any `dependencies` or `devDependencies` listed therein available to be imported.
+
+Internally steal uses an included [npm] module to facilate this, but you largely don't need to know about that.
+
+## Installing and using Packages
+
+Install dependencies using the [npm install](https://docs.npmjs.com/getting-started/installing-npm-packages-locally) command. Steal only knows about packages that are saved within the `dependencies` and `devDependencies` properties in your package.json. With newer versions of npm, installs are saved as a dependency by default, in older versions you have to use the `--save` or `--save-dev` flags.
+
+Here's an example of installing the [jquery](https://www.npmjs.com/package/jquery) package:
+
+```shell
+npm install jquery --save-dev
+```
+
+And then using it in [steal]:
+
+```js
+import $ from "jquery";
+
+$("body")...
+```
+
+## Troubleshooting troublesome packages
+
+Occasionally you might encounter a package that fails to load. Often this is because you are importing the package's *raw source* code that depends on specific bundler configuration, or intends to be run in Node.js. StealJS tries its best to emulate a Node environment but there are limitations.
+
+Most packages include distributables intended for browser usage. You can find these by looking in the `node_modules/[PACKAGE]` folder. Often it is in `node_modules/[PACKAGE]/dist`. This is where jQuery's distributables are located and looks like this:
+
+```
+core.js
+jquery.js
+jquery.min.js
+jquery.min.map
+...
+```
+
+In the case of jQuery its package.json is correctly configured, so Steal loads the right file. For other packages that might not be the case. You can configure this yourself. In your package.json add a __steal__ property if it doesn't already exist:
+
+```js
+{
+  "steal": {
+
+  }
+}
+```
+
+Let's assume we have a __foo__ package, and its distributable is located in `node_modules/foo/dist/foo.js`. This configuration will let you import foo correctly:
+
+```json
+{
+  "steal": {
+    "map": {
+      "foo": "foo/dist/foo"
+    },
+    "meta": {
+      "format": "global"
+    }
+  }
+}
+```
+
+> *Note* that the [config.meta] configuration is often not needed. Only add it if it doesn't load without.
+
+This uses two types of configuration. [config.map] configuration tells steal that when it encounters the __foo__ specifier, load __foo/dist/foo__ in its place. Secondly the [config.meta] configuration tells steal that this module is a *global*.