Typescript, Webpack, and SharePoint for Dummies

It’s all about the build.

Getting the Tools

The first thing you’re going to need to install is NodeJs.  Download the latest Long-Term Support (LTS) version, which is 6.11.2 as I’m writing this.  You can take the defaults all the way through the installation.

Now you’re going to need some sort of JavaScript editor with Typescript support.  I’m going to use Visual Studio Code (VSCode) throughout this post, but you can use whatever editor you want.  This too is a next -> next -> finish installation; you can take the defaults throughout.

Next, we need to get Typescript.  To do that, we’re going to use a tool called npm (Node Package Manager), which was already installed with NodeJs. npm is a command-line tool, which sadly you’re going to have to get used to for now if you’re going to do this kind of development.  So, in VSCode, go to View -> Integrated Terminal and type:


npm install typescript -g

in the terminal:



This installs the latest version of typescript, which is 2.4.2 at the moment.  If you wanted to install a particular version of typescript, the syntax is:


npm install typescript@1.8 -g

The -g option for npm means install it globally (as opposed to just for our current project).  This allows us to run Typescript commands from the command-line, so to compile you can just go to the terminal and type:

tsc

which at the moment will just yield a big usage message since we don’t have any code to transpile yet. We’re also going to want to configure Typescript a bit, but I’ll put that off until we have something to transpile.

npm is a general-purpose tool to manage dependencies for JavaScript projects, which we’ll be using quite a bit throughout this and subsequent tutorials in this series. You will need to get familiar with it, but I’ll explain each new option as I use it, so you will get reasonably familiar with it just following this series.

Creating a Rudimentary Project Structure

In VSCode, click on the explorer (the first icon on the bar to the left).



Click on the Open Folder button; the right click and create a new folder called tkoGettingStarted, and select that folder. 



Click on the folder tkoGettingStarted in the explorer. Notice the icons that appear next to the folder when you click on it. The first is to create a new file in the folder and the second is to create a new sub-folder. Click the New Folder icon.  Enter src and hit OK.  Repeat, but this time enter build as the folder name.  Your explorer should now look like: 



Now there’s a pretty good chance we’re going to want a bit more project structure before we’re done, but this is good enough to get started.

Adding Some Code

Now we need to add some code.  For now, it’s not going to be very exciting code, in fact it’s going to be your basic hello world type of code mostly borrowed from the Typescript Knockout Starter code on GitHub.  Create a file in the src directory called helloViewModel.ts and put the following code in it:

This is a simple Knockout view model in Typescript.  I’m not going to talk a lot about the code now, first of all because it’s pretty danged boring code but also because as previously stated, this post is all about the build.  But basically I have a Typescript class call HelloViewModel with two properties, language and framework.  Both of the properties are of type KnockoutObservable, which is the foundation of the Knockout library and allows the view model to wire up two way data binding between the view (HTML/DOM) and the model (normally some sort of data store, ultimately we’ll be using SharePoint for this).  Don’t get me started on the terminology; I’ve always thought that the Model View ViewModel pattern was perhaps the worst named pattern in the history of design patterns.

Now to understand this next small bit of code you need to understand a little about Webpack, which is going to be used to bundle my code into a package for deployment.  By default, Webpack is going to bundle my code up into an island unto itself, meaning it will do whatever its going to do when it’s loaded into the browser without anybody having to call into it and tell it what to do, in fact nothing will be able to call into it because nothing will be exposed to the outside world as a global. But I want to write something that could be used from one or more SharePoint web parts, and those web parts might want to initialize the HelloViewModel with different parameters, in fact it would be a pretty dumb web part if it couldn’t do that.  I’ll get into the details of how to make Webpack do what I want in the next section but now I want to write a small class that I’ll expose to the outside world as the interface to my library.

Create a second file in the src folder called index.ts, and put the following code in it:

This code is a little simpler.  It exports an object literal with a single method called initHelloViewModel (which coincidentally, initializes the hello view model ;).  The most interesting thing here is the call to ko.applyBindings, which is another fundamental part of Knockout.  This call binds the view model to the view.  It takes in, at a bare minimum, the view model, but there is a second parameter which is an HTML element, and it is the root element to which our model will be bound.  You don’t often see this second parameter used in Knockout samples and tutorials, but if omitted the binding occurs to the entire body of the page, which doesn’t make a lot of sense in a SharePoint world where generally different web parts control different parts of the page.  So I’m generally always going to pass in an element to bind to, and it will be an element that resides somewhere within my web part.

That’s really all the code we’re going to need for this tutorial.  I did mention that it wasn’t going to be very exciting code didn’t I?  But there is one more thing I need to do code-wise, and that is to provide some configuration for the Typescript compiler (tsc).  To do that, create a file in the root of your project call tsconfig.json, and put the following in it:

Basically, this configures Typescript as follows:

  • include: compile all .ts files in the src directory and any sub-directories.
  • outDir: put the results of compilation in the build directory.
  • lib: include es2015 (i.e. ES6) and dom (i.e. the HTML DOM).
  • sourceMap: build a source map along with the compiled output, which if deployed with the output allows us to debug as if we’d deployed the original Typescript instead of the compiled version.
  • noImplicitAny: in typescript you need to specify types for things. If this is false, then anything you don’t provide a type for will be assumed to be of type Any, which means why did you bother using Typescript.
  • module: This is the module format to be used, commonjs is kind of standard for browser-based applications.
  • allowSyntheticDefaultImports: ok, this is a bit advanced, let’s just leave it at I like true for now.
  • target: es5 is the same old JavaScript we’re all pretty used to, the browsers are used to it to, so for now this is always going to be the target. Typescript will be transpiled down to this.

Ok, so we have a basic project structure, some source code, and we’ve configured Typescript; surely we’re ready to compile something. Not quite. We’ve used Knockout in our source code, and to do that we have import statements that import Knockout, but Typescript has to know where to find Knockout. We can configure Typescript to find it directly, but Webpack does it a bit differently and since ultimately we plan to use Webpack lets start talking about that.

Putting it All Together

The first thing we need to do is initialize our project. To do that, type:

npm init

in the console.

Leave a Comment