Are you new to the SharePoint Framework?… In this eBook you will learn about your toolset for SPFx development: Node.js, NPM, Yeoman, VS Code, Webpack…but most importantly you’ll learn what you can ignore, and what to focus on.
SharePoint Framework Development allows you to develop using modern web development skills, which can be applied to any other development project. You can take the skills which you learn in a SharePoint Framework development project, learning how to use open-source frameworks, React and other technologies all of which can be applied to other web projects.
In this eBook companion to the Virtual Summit session, we will be looking at what the SharePoint Framework is, why we need it, understanding the development toolchain, and finally building client-side web parts.
History of SharePoint Development
SharePoint development, much like the product itself, has evolved over a number of years. Let’s take a quick look at the journey to help us understand how we have arrived at the SharePoint Framework.
The initial versions of SharePoint Portal Server were based on .NET framework 2.0. Customisations were developed using VB.net or C# and were only able to use a server-side API, no client-side API existed. Any customisations that were developed needed to be full trust solutions, but as no packaging framework existed, everything needed to be deployed manually.
Microsoft Office SharePoint Services 2007
MOSS 2007 was based on the next version of .NET, using .NET version 3.0 but still only offered customisations using the server-side API. Still, customisations ran as full-trust solutions, however, a new deployment mechanism was added, whereby they could be packaged up as solutions and then deployed using the new feature framework.
SharePoint 2010 changed the development model by introducing the concept of sandboxed solutions. These solutions were partial-trust which meant that you didn’t need to deploy them to the server, you could upload the solutions directly to a site collection. This did mean however that solutions were limited only to a single site collection.
SharePoint 2010 also introduced the client-side object model which allowed remote calling to SharePoint, so again removing the need to install code onto the SharePoint server itself.
SharePoint 2013 & SharePoint Online
Provider hosted add-ins, on the other hand, relied on a two-tier model, where the logic was stored and executed on a remote server, using the client-side object model to call back into SharePoint, while the presentation of the add-in appeared directly within SharePoint. Whilst this gave a lot of flexibility in terms of being able to develop customisations, the implementation within SharePoint wasn’t great as add-ins would effectively run as a subsite of the site collection and be viewed using an iFrame on the SharePoint page.
This method of development became more and more popular, and this shift in development methodology was noticed by Microsoft. This change of methodology is what gave birth to the modern way of developing customisations, using the SharePoint Framework (SPFx).
What is the SPFX
SharePoint Framework provides full support for client-side customisations as well as giving us easy access to SharePoint data through an API that handles the authentication for us. This means that developers don’t need to worry about authenticating against the REST APIs, i.e. reaching out to Azure AD to get an access token which is then included in any calls, because the code runs within the context of the user who is logged in.
The new SharePoint Framework model embraces the modern web development stack, which means that developers no longer need to have specialist SharePoint skills to be able to develop. The skills which modern web developers have can be easily applied to SharePoint Framework.
Customisations created in the SharePoint Framework are also very flexible, as they work in both classic and modern sites. It should be noted that SharePoint Framework web parts will work in classic sites as well as modern sites, however classic web parts will not work in the modern experience. The only way you can develop for both experiences is using the SharePoint Framework.
The SharePoint Framework isn’t just a development methodology being used by third-party developers. Microsoft is also using the SharePoint Framework for developing their web parts, which means that they will find the same limitations that, we as a non-Microsoft developer. If they find those limitations, they are likely to resolve the issue which then benefits everyone.
Now that we understand what the SharePoint Framework is, we need to ensure that we have the correct tools to support the development
Regardless of what tools you use for the actual development, there are resources which you will use throughout the process of creating your customisations.
The workbench is a virtual SharePoint page that allows you to create and validate the basic functionality of your customisation without physically touching SharePoint. When launched, it actually launches a web page on localhost.
Once you have confirmed your basic functionality using the workbench, you will need to deploy it to SharePoint to ensure that any data interactions are working correctly.
You don’t necessarily need a developer tenant; however, you can get one for free from Microsoft which gives you access to the full capability of Office 365. The idea is that you have a full-blown SharePoint environment where you can test your web parts which are isolated away from any production tenancies which your organisation may have.
Having a tenancy, such as a developer tenancy, means that you can then test your web part against data within SharePoint through the SharePoint workbench. The difference now is that rather than the workbench being hosted on localhost, you would access it from a SharePoint Online site by accessing a URL similar to:
Now we need to look at the tools which we will use to develop our customisations.
Earlier we looked at the evolution of SharePoint and how the development practices changed. The tools which we use have also evolved. Let’s first of all look at what we would use in traditional development and look at the technologies which have now replaced them.
|Classic Development||Modern Development|
|Visual Studio||Visual Studio Code |
There are different versions of Node.js available, so always check on the SharePoint Framework documentation to confirm which version you should be using. Generally, it is recommended that you use the Long-Term Service (LTS) release.
Every development toolset has the ability to create or use packaged code, including any dependencies for the code. In traditional development, this took the form of NuGet packages, however, in modern development we use NPM to install and manage those packages from the command line.
Visual Studio Code
Visual Studio Code is a source code editor developed by Microsoft for Windows, Linux and macOS. It includes support for debugging, embedded Git control, syntax highlighting, intelligent code completion, snippets, and code refactoring. This is an extremely lightweight development environment that serves as an alternative to the full-blown Visual Studio application. It is designed to support modern web development, having a built-in command-line console so that you can easily interact with commands such as NPM.
Yeoman is the scaffolding tool that will create the basic structures needed to support the development of the customisations.
Think of this as going to New Project within Visual Studio, which would automatically create the basic folders and files needed to get the basic customisation up and running.
Gulp is a modern development equivalent of build jobs which we used to use within .NET development. The idea is that it will provide levels of automation around the compilation, packaging and deploying of your customisations so that you don’t have to do everything manually.
Node Version Manager (Optional)
There are actually two different projects relating to the Node Version Manager (NVM). NVM is actually a Mac/Linux only project, therefore if you are a Windows user then you will need the Corey Butley version of NVM which can be accessed from the following link:
NVM provides the ability to easily switch between different versions of Node.js, which is particularly useful if you want to test modules with the latest version of Node without having to remove your more stable release version.
Full install instructions are available from the Corey Butler GitHub repository.
One of the most useful commands available is to check what version of Node is currently installed, which can be found by running the command: node -v
Using NVM, I can then get a list of all available versions of Node, using a command which will speak to the Node.js website API. What gets returned is a list of all versions of Node which I can install.
To do this we need to run the following command:
This will return the entire list, including highlighting specific versions such as LTS releases as well as showing which version you currently have running.
Getting Started with creating a web part
There are a number of very good guides available on the SharePoint Dev pages (aka.ms/spdev-docs) which will guide you through the set-up process for your environment. That will guide you through the installation of Node.JS including advising the version that you should install, right through to creating your first web part.
Creating the web part
Step 1 – Create the directory (if you haven’t already created it) by using the command:
Step 2 – Navigate to the folder by using the command:
Step 3 – Create a scaffolded SharePoint Framework Web part by using the Yeoman generator. Enter the command:
Step 4 – Enter the name of the web part
Step 5 – Select the version of SharePoint which you are going to be developing for. Notice here that there are different options such as SharePoint 2016. This is because there are different versions of the SharePoint Framework available on SharePoint 2016, and on SharePoint 2019 compared to SharePoint Online. The difference in the versions is because SharePoint Online is consistently being updated when compared to on-premises servers, and the same can be said for the SharePoint Framework.
Step 6 – Enter the requested information in each question or just accept the defaults
Step 7 – When prompted for the framework, select no framework. Once we have completed the questions, the web part creation will take place. You will see that there are resources being pulled down to your local machine. This is where modern development is most notably different. In classic, all of the files and configurations required by the project already exist, whereas, in our new development environment, they are downloaded as part of the creation process.
Step 8 – Once the creation is completed we have got the bare bones of the web part which we can now open in our chosen editor.
Step 9 – When we open the files in a tool such as VSCode, we will see the files and can now begin our development.
The main class is the HelloWorldWebPart class which contains a number of methods, the first being the render method. This method contains the code to determine how the web part will look and feel, notice that you can create your HTML here to stipulate the web part layout.
The second element to draw your attention to is the getPropertyPaneConfiguration method which allows you to define what is seen when you edit the web part in SharePoint and get access to the properties screen. In this example, we are just going to get a description.
Now that we have created the web part, let’s run it.
Running the Webpart
In order to see our part, we now need to use a Gulp task to fire up the local workbench and view the web part. Whilst the workbench is intended to act as a “preview”, any functionality which you write into it will be available for you to try here.
Once the gulp task runner has finished processing, your default browser will launch and will open the local workbench.
It looks and feels like a modern SharePoint page, where I can go and add my web part. To do this click on the + on the page, and you will see our web part created. Simply select it, and it will appear on the page. We can also interact with the web part by editing the properties, which will open the properties blade and allow me to change the description text appearing in the web part.
A really cool thing relating to the SharePoint Framework is that if you leave the browser open and return to VSCode, you can update your web part and those changes will automatically flow through into your workbench so that you can (almost) immediately see your modifications.
What else can I create?
As well as being able to create web parts, there are also other customisations that can be developed using the SharePoint framework.
Field customizers are the modern equivalent of JSLink, whereby we can apply some custom rendering to a cell within a list. Unlike SPFx web parts, this will only work on modern lists. Should you wish to achieve the same goal on a classic site, then you will need to use JSLink.
Command Sets are similar to custom actions from classic development and allow us to add buttons to the toolbar or the context menu on an item or document. You can specify the conditions when a command becomes available, e.g. whether it appears when no, one, or multiple items are selected.
We looked at the key tools which we need to be able to create our customisations, including Node.JS, Yeoman, VSCode as our development environment, Gulp etc.
We then went through a basic introduction to creating a SharePoint Framework web part which started with creating a folder and then using Yeoman as the scaffolding tool, to create the folder structure and relevant files needed to get us up and running. Remember that there are different versions of the SharePoint Framework needed for SharePoint 2016, SharePoint 2019 and SharePoint Online, so ensure that you select the right version when creating.
Once we had generated our web part, we then previewed the web part, in an interactive sandbox called the Workbench which runs locally on the development machine. Whilst the webserver is running, any changes made to the web part will automatically be made available to the workbench.
Finally, we looked at how the SharePoint Framework can be used to customise other areas of a SharePoint page through the use of extensions. Extensions allowed us to add additional content to placeholders using Application Customizers, change the look and feel of a cell in a list by using Field Customizers, and Command Sets which allow us to create additional options on toolbars and item context menus.
Full documentation for the SharePoint Framework, including tutorials and guides, can be found at the SharePoint Developer site https://Aka.ms/spdev-docs