Adventures with the SharePoint Framework (SPFx): Part 1 – Getting Started

In this article we’ll get started with developing for the SharePoint Modern User Experience (UX). If you don’t know what the SharePoint Modern UX is and why you now need to add developing with SPFx to your arsenal of methods, techniques and paradigms, then please go and read my previous article, All Mod Cons, which explains all of that stuff in detail.

There are actually some really good articles and step by step tutorials put out by Microsoft and others on the SPFx and I would strongly recommend that you read and follow them, to get yourself up to speed. I recommend starting here https://docs.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview.

Well if Microsoft has done such a great job of explaining things then what’s the point of this article? Well, I plan to cover off the stuff that they don’t tell you. Stuff that you really only discover by doing things and building stuff for real and not just for the on-rails basic knowledge you might acquire by following a tutorial. So, let’s get started.

Setting up a development environment

This is fairly straight forward and the steps are clearly spelt out in the Getting started article accessed from the above link. Basically, you need an O365 tenancy that you can develop against and a client machine from which you can cut some code.

Setting up and O365 Tenancy

If you don’t already have access to an O365 tenancy it’s fairly easy to acquire one. You can either take a month’s free trail of O365, leading to a commercial subscription for which you have to pay of course. Or you can join the O365 developer program, which gives you a year’s free run. Once you have a tenancy at your disposal you will need to set up an App Catalog site. This is fairly easy to do and the steps are explained here. You need an App Catalog as this is the place in which you will upload your solution, in a .sppkg file, so that it is registered with your tenancy and can make it available for use within SharePoint sites.

A feature of the way in which the SPFx has been constructed is that the .sppkg file that registers the fruits of you creative genius will need to access various resources including images, JavaScript, CSS files and other artefacts and these need to be stored somewhere that is accessible to your solution. Now it is possible to just store these artefacts in a SharePoint document library, typically the Site Assets library is used for such purposes, but that runs the risk that someone might tamper or delete stuff and so break you code. You can also save these assets in a Content Deliver Network (CDN) say on Azure and that is totally supported and would probably be a better option if you were developing a commercial product. However, it turns out that you O365 tenancy can be configured to be its own CDN. Sadly, you can’t do this from the O365 Admin Centre, you have to run some PowerShell to set this up. I won’t go into details here because the steps are all adequately described in the following article Enable CDN in your Office 365 tenant. As you will more than likely want to use the tenancy’s CDN, even if it’s just during development cycles, I recommend you sort this out now and be done with it.

Setting up the development client

The good news here is that you don’t need to use Windows Server machine with SharePoint installed to do any development with the SPFx. In fact, you can do this on essentially any machine, it doesn’t even have to be Windows. You can also potentially use any code editor of your choice but Microsoft suggest using Visual Studio (VS) Code which is free, relatively light-weight and quite a capable development tool for our purposes. Don’t get fooled or confused by the Visual Studio prefix of the tools name. VS Code is a complete separate application that has no dependencies on or relationship with the long standing Visual Studio IDE which you may be familiar with.

Using VS Code might actually cause a few issues for Pro Developers which use Visual Studio IDE and/or VS Team Services for source control as it means that SPFx development might have to be conducted outside of their normal tool set. As it happens, you can use Visual Studio IDE for the SPFx development as the community has come up with a solution template for doing so. However, we’ll keep that for a different day and for now we’ll take the path of least resistance and simply download and install VS Code on the machine you are intending to use for development.

Just to recap:

  • You need a client machine to do the local development but it doesn’t need to be a Windows Server machine and it doesn’t need SharePoint installed and doesn’t need the Visual Studio IDE either.
  • But you do need a half decent code editor and although you can pick anything you want, Microsoft offer you a pretty good one for free called Visual Studio Code.

Next, you have to configure the development machine with a few software components, specifically:

  • NodeJS: This is responsible for harvesting all the libraries and resources your solutions will need, in order for it to work.
  • Yeoman: This is a scaffolding tool that which is the foundation for a Microsoft provided extension to Yeoman which also have to install and which actually provisions the folder structure of your projects.
  • Gulp: This packages and links everything into a solution that can then be deployed for testing and ultimately as a .sppkg file which can be uploaded to your App Catalog.

I won’t go in to the details of what needs to be done to install these components as it is all explained, more than adequately, in the article Set up your SharePoint Framework development environment, but in brief you:

  • Download and install NodeJS
  • Use the Node Package Manager (npm) provided by NodeJS to install Yeoman, the Yeoman SharePoint generator
  • Use the npm to install Gulp

All of this is done at the command line or the PowerShell Console but be prepared, this all takes quite a long time, so make sure you have couple of hours with other stuff to do while this all cooks in the background.

Setting up your development environment my manually running PowerShell scripts feels very antiquated to me and reminds me of running .bat files of 2 decades ago. Still, no one else seems to care.

When all is done you are safe to proceed and work your way through the tutorials.

A few things to note

So here are a few of things that nobody thought to tell you. Everyone says what a great improvement in productivity the SPFx is, as you don’t have to provision servers, install SharePoint and Visual Studio etc. All of that is true but TBH I had all of that stuff up and running in any case and so it didn’t really save me any time at all. In fact, installing Yeoman and Gulp was not a 2-second job so I’m not really swayed by this argument.

Next, the commands you enter into the command line console are slow. You might have to wait 30 seconds from when you type “yo @microsoft/sharepoint” before you get any response back from the console, leaving you wondering if anything is actually happening and should you just abort with a CTRL+C. So be patient.

After you respond to the parameter prompts and define your project, Yeoman kicks off and the command line whirs in the background to let you know that stuff is going on. However, provisioning a project takes an age. For this blog I timed it and it took a spit under 10 minutes. Actually, the first time you do this it takes considerably longer because it downloads some zip files that it can reuse the next time around. The first time I ran Yeoman, from when the provisioning process started to being in a position to write my first line of code, took half an hour I reckon. That’s is hardly conducive to efficient development in my book, yet no one seems to point this out.

Still, it’s hardly surprising it takes that long, take a look at the contents of the project folder!

Over 400 MB of diskspace, 66 thousand files spanning over 6 thousand folders, just to provision a simple Hello World Web Part. You have got to be kidding me!

Added to this, as Yeoman does its stuff, it spits out dozens of warnings of libraries that are deprecated or should be updated and this does not really instill much confidence. Where on earth would I start trying to figure out an issue in amongst 66 thousand files.

The Local SharePoint Workbench

Oh, well just ignore the warnings and hope for the best by running a “gulp serve” as the Yeoman generator suggests as it completes its duties and if all is well then after about 20 seconds or so you get taken to SharePoint Workbench where your first client-side web part can be seen, just waiting to be installed.

The first time around the buoy you should also run the “gulp trust-dev-cert” command. This tells Gulp to, you’re guessed it, trust a certificate that we use apparently use for testing. As it seems we have to do this if we want to do any dev work then why is this not magically just take care of for us, – beats me?

Now, here is a big fat gotcha that no one tells you about. On my development rig, I don’t like to work with projects on my local machine. Instead, I have a NAS of sorts and like to store all my project code where it can be accessed from a mapped network drive. This way, I can develop from my laptop or remote in to a server or whatever and basically not have my source code tied to a specific machine. It makes sense, to me at least. So, when I first tried to develop an SPFx project I naturally created the project folder on a mapped drive. Yeoman worked just fine but Gulp didn’t. Running a “gulp serve” command just never returned from processing and I left it for hours (see how patient I was)! It seems Gulp just does not like mapped drives. Move everything over to the C: drive and it all works swimmingly. This cost me several hours of head scratching and it doesn’t really make sense but I do wish that some one had told me before hand, so that’s what I’m doing for your, right now.

The Workbench is made possible be spinning up a local web server, deploying your solution and opening up a browser window so you can see the fruits of your labour on a page, the Workbench. This means you can test the basic plumbing of your client-side web part without the need to reach out to your tenancy.

This is something else that nobody explicitly tells you, the Workbench is only of use when you are developing client-side web parts. It has nothing to offer if your solution is a SharePoint Extension. I should explain. As you work your way through the Yeoman provisioning wizard, one of the early questions it asks you is whether this solution is to deliver a client-side web part or a SharePoint Extension. If you choose the web part option then the local Workbench is your friend and all is good. However, if you choose the Extension option then you have another decision to make about the type of extension your solution is to deliver, and the options are:

  • Application Customizers: These allow you to add scripts, styles and HTML to placeholder elements on Modern Site Pages. These are much like the JavaScript injection technique or Delegate Controls of traditional server-side development which provide a mechanism by which you can add custom content to pages without creating a custom master page. In Modern, we have no master page of course but the concept is similar in that Modern pages have placeholders in which we can add what we like (so long as its client-side). Actually, we only have 2 place-holders to work with at the moment, you can add a payload to either the header or a footer placeholder, or both if you like.
  • Field Customers: Provides a way to render column content is a custom way.
  • Command Sets: Provides a way to create new action buttons and menu items.

Now it is entirely possible (or so it is claimed) to develop a SPFx solution that delivers multiple artefacts. A single package might deliver 3 client-side web parts an Application Customizer and a Comment Set for example. I haven’t gone far enough in my travels yet to confirm or deny this but for now we’ll take Microsoft at their word.

For the purposes of getting started we’ll stick with developing client-side web parts for now and we’ll leave extensions for another day.

The Tenancy Workbench

The local Workbench will only take you so far but your SharePoint sites in O365 all no come with their own Workbench application page in the 15 hive. There is no hand link to the Workbench from a SharePoint site and so you have to assemble the URL yourself in the format “{SharePoint Site URL}/_layouts/15/workbench.aspx”. If you just access such an end point through the browser it will give you this warning message.

What this is saying is that if you want to try out your web part then you need to have gulp running. To do that you can execute a “gulp serve –nobrowser” command and when Gulp stops spitting out text, try and access the Workbench again and all being well your web part will show up on the target site of your choice. Just add a web part instance to the section which already exists on the Workbench page.

Your web part might take some finding as it will be added to the “Other” group and that might have lots in it already.

All being well you will be able to add the Hello World web part of the tutorials to the page.

The main difference between the local Workbench and the tenancy Workbench is that the latter can be used to interact with SharePoint data. The tutorials guide you through the process of creating a fake data model so that you can use the local Workbench to simulate the interaction with SharePoint data. I can’t see the point in that myself. It’s seems like a lot of effort for not a lot of gain, considering how easy it is to test against a real site. I could be missing something here.

Summary

So, there we have it. My first tentative steps into the SPFx. There is still lots to do. Apart from doing something useful with our web part, beyond hello world, we’ve got to package it up and upload it to our App Catalog. We’ll be covering that in the next part of this series.

3 comments

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s