External Dependencies in the Client-Side Framework

There are thousands of npm packages out there on the internet, the new SharePoint Framework allows developers to make use of these. This article walks you through the process of adding external packages to your project.

WARNING: This was produced with pre-release material and is subject to change!!

Once you get your hands on the SharePoint Framework, one of the first things you’re going to want to do is start building applications using some of the tools and technologies you’re familar with. AngularJS might be one of those, but this tutorial works for any project which is hosted in an npm repo, and has TypeScript typings available in DefinitelyTyped. You can of course create your own TypeScript definitions, and npm packages…but let’s walk before we run ;)

So, as a first step, we need to understand the anatomy of a client-side application, I’ll stress again this is pre-release.

There’s three important files

  • .\package.json This config stores information about your npm package, but most importantly for us - the dependencies.
  • .\typings\tsd.d.ts This includes references to all our TypeScript definitions. These definitions allow for intellisense in VS/VSCode and ensure syntax and typings are correct.
  • .\config\bundle.json This config file helps us define the source of our external packages and configure WebPack/System.js. Both important elements in building client-side solutions.

Installing the npm package

In order to get going, we need to install our npm package. In this case, it’s AngularJS, which is called angular. So, to do this run the command below and also observe the changes to .\package.json

npm install angular --save

Configuring bundle.json

By default, your new package will get bundled into your application, which we want to avoid. Ideally, we want to use an external CDN for libraries. In order to do this, we need to do two things.

  • We need to exclude angular from the bundle, by adding it to the exclude array. This will ensure WebPack doesn’t add the AngularJS library doesn’t get added to our output file (in this case intranet-application.js). This prevents our application bloating.
  • Add a reference to angular in the config.paths object. The config object is used by the @ms/sharepoint bundle task, and uses system.js to load dependencies. Adding angular to this object tells system.js to load AngularJS from an external CDN.
{
  "entries": [
    {
      "entry": "./lib/intranetApplication/IntranetApplicationApplication.js",
      "outputPath": "dist/intranet-application.bundle.js",
      "configPath": "dist/intranet-application.config.js",
      "useWebpack": true,
      "exclude": [
        "@ms/sp-client-platform",
        "angular",
        "react",
        "react-dom"
      ]
    }
  ],
  "config": {
    "paths": {
      "angular": "https://ajax.googleapis.com/ajax/libs/angularjs/1.5.0/angular.min.js",
      "@ms/sp-client-platform": "dist/sp-client-platform.js",
      "react-dom": "dist/react-dom.js",
      "react": "dist/react.js"
    }
  },
  "baseUrl": "http://localhost:4321"
}


Adding TypeScript definitions

In order to use AngularJS in our IDE of choice (because you get to choose now!), we need to add the TypeScript definition. First, run the command below to get the typings, whilst observing the .\typings folder. You’ll see a new folder called angularjs appear with angular.d.ts in it.

tsd install angular

Next, we need to add a reference to this file in .\typings\tsd.d.ts. Add the line below to the file

/// <reference path="angularjs/angular.d.ts" />

Get using your new library

The final step in config, is to reference the Node.js package. In your application, typically .\src\[YourAppName]\[YourAppName.ts], add your package. In the case of AngularJS, the syntax is below.

import 'angular'

Now go to your workbench, and look in Developer Tools, you’ll observe your library has been loaded from the path defined in bundle.json

AngularJS Loaded!