• AndyH

Getting set up with SPFx

Updated: Mar 13, 2019


In this first blog post I am going to summarise the areas I focused on and the resources I found useful to get set up and started. The links below contain all the details you need so I won't repeat it here. However, I have added what I learnt from my experience going through it.


The tools we need to create an SPFx web part are:

  1. NodeJS and NPM. NodeJS is a JavaScript runtime environment and we need this to drive many of the tools. NPM is the package manager that is needed to install all the wonderful open source libraries that our web part will use. Note that at the time of writing you must install NodeJS version 8 and not the newer version 10 as Yeoman does not yet support it.

  2. Yeoman and Gulp. Yeoman is the SharePoint web part generator used to create a new empty project. Gulp is used to automate the build process and start serving the web part locally.

  3. Visual Studio Code. You will need an editor to work on your project code and you could you anything you are comfortable with. However, Visual Studio Code has been widely adopted because it does everything you need and more. Plus it works on Mac and Linux too.

  4. A command line tool - Windows CommandLine, Powershell or any third party program would be fine.

So let's get started, install and configure the above tools as per Microsoft's guide:

Several things to note:

  1. Remember to trust the local developer certificate as you need to complete this step in order to test your web part: gulp trust-dev-cert

  2. I needed to install the node msi file through the command line due to a policy on my machine: msiexec -i node-v8.15.0-x86.msi

  3. You will need a SharePoint Online site to be able to test the web part with lists, libraries and other resources.

  4. I'm using Azure Dev Ops to manage my project and source control (GIT) as this is what I have been using for development already. Best not go anywhere without source control!

Creating a hello world web part


The Microsoft Docs site has a series of tutorials that walk you through the creation of a web part and a number of other topics such as deployment to the site. There is also an introduction to an Office UI Fabric React component. So they are worth following along with:

TypeScript


The code generated from Yeoman in the tutorials is TypeScript which is a super-set of JavaScript and in this project it actually transpiles down to regular JavaScript anyway. There is no reason why you could not use JavaScript if you wanted to but there are a number of advantages of TypeScript so this is what I'll use.

Being a C# developer there is a lot in common that I recognise in TypeScript. There are no shortage of tutorials on the Internet to fill in the gaps in my knowledge but I found a no-nonsense book that suited me nicely by Thomas Claudius Huber.

I can recommend this if you have some prior experience of programming because it just focuses on describing the language and not retread endless beginner details such as "what is a variable". Something very much appreciated as I have enough to read up on as it is.


React and Office UI Fabric


If you followed through the Building your first web part tutorial or have tried the Yeoman generator already, you would have seen the option to to use React. Much of what you see on Office 365 is using React components and Office UI Fabric so it makes sense that this is something I should use.

React immediately reminds me of my days programming classic ASP and more recently with MVC and Razor pages in that it sort-of mixes code and presentation together. Developers may baulk at this concept but it does provide some advantages if you keep your code in check and I am understanding the rationale after a couple of weeks using React.


What is important to know about React:

  1. React components are generally written in a file with a TSX file extension (JSX for JavaScript) and TypeScript knows what to do with it in our SPFx web part.

  2. HTML elements are written as part of the code, not as a string. For example: const element = <h1>Hello, world!</h1>;

  3. HTML elements must be XHTML compliant, written in lower case and must have a closing element.

  4. You can create your own React components which can be described like a user control in ASP.NET. These must begin with an uppercase character, but otherwise look like HTML. For example: const element = <ContactDetails />

Patterns & Practices JS


One last part of the puzzle for now is Patterns & Practices JS, or PnPJS, which hides much of the verbose REST code you would otherwise have to write when talking to SharePoint.

It immediately looks familiar for .NET developers who have used the SharePoint object model. It even has IntelliSense code completion in Visual Studio Code. PnPJS is its own thing, however, and I found you have to understand the SharePoint REST API's and also enough JavaScript concepts to consume them.


It's important to be aware that PnPJS initially started life as PnP JS Core and as late as July of last year it transformed into PnPJS. Fortunately, much of the example code found on the Internet for Core appears to only need minor modification to use under PnPJS.


I'll post more about using PnPJS in the future.


Next steps


That's quite a lot of information for one blog post but I wanted to summarise the relevant parts I am using in my SPFx journey. I have one further link from last years Collab365 that I found most useful for bringing understanding or React, Office UI Fabric and PnPJS together.

While this is not using SPFx to build a web part (it describes JavaScript injection instead) and the examples refer to the older PnP JS Core, Ryan does an excellent job demonstrating how to bring many elements together.

149 views