Getting started with the SharePoint Framework SPFx

On May 2016 the SharePoint Framework (short SPFx) was announced and just about a month ago it has been released and was made available for the general public.

So what is the “SharePoint Framework” and how do you get started with it? In this blog post I try write down an easy to follow guideline on how to engage with the SPFx and to understand the overall ecosystem, customizing and deployment tasks. I have been following the development of the SPFx for some months now but never really started using it. Now the time has come and I’m going to document my way to “full SPFx enlightenment” 😉

The SharePoint Framework (SPFx) is a page and web part model that provides full support for client-side SharePoint development, easy integration with SharePoint data and support for open source tooling. With the SharePoint Framework, you can use modern web technologies and tools in your preferred development environment to build productive experiences and apps on SharePoint that are responsive and mobile-ready from day one!

Background

My background is more likely of the “old school” SharePoint developer. I started in 2013 to develop Feature based Solutions that were deployed with WSP packages and all that stuff. This involved a lot of C# code, declarative XML files and some web assets like CSS, HTML, JavaScript. Deployment was often like hell. In the worst case it led to server downtimes. Not so cool. But it worked and with the right portion of caution it was effective – but still time consuming.

At the same time Microsoft introduced the AddIn model. I didn’t put much effort into that but at all I found a bit strange and still clumsy. So I began to develop plain solutions by mostly using the CSOM way of customizing SharePoint sites. With this developing model it is ensured to only work on a client side and don’t touch the SharePoint server locally. No GAC deployment, downtime or anything else involved like with the “old Solution” model. I still love to use CSOM because C# is running through my blood and I like the overall API. It’s a nice way to engage and customize SharePoint artefacts, especially with the Office 365 PnP Core Framework which relies on the CSOM libraries.

The downside of this approach is that it is not possible to develop and provide any kind of SharePoint Web Parts the user is used to. So here the new SharePoint Framework comes into play.

Introduction

To get a detailed introduction what the SharePoint Framework is I recommend you to dig into the official Office documentation of SPFx here. Furthermore you get the most recent updates on Twitter like from Vesa Juvonen, who is a Senior Program Manager for SharePoint and Office 365 and I recommend the official Office 365 Dev PnP and SharePoint Twitter accounts.

I myself also watched the SharePoint Framework SPFx Webinar by Andrew Connell which provides a great introduction to SPFx.

Tooling

To get started I organized all the recommended tools to create SPFx solutions in a way of best practice.

    • Visual Studio Code
      As Andrew Connell described in his webinar the “classic” Visual Studio (I mostly use 2013 & 2015)  is overloaded with special features that have no single advantage on developing SPFx solutions. So the recommendation is to use the lightweight (and quite portable) Visual Studio Code IDE. To get started on how to install, configure and use the IDE you get here a lot of documentation.
    • Node.js & NPM
      The JavaScript based engine is a widely spread runtime that is being used in many projects to build scalable network applications. It also includes one of the biggest package managers called npm.
    • TypeScript
      To make life with developing JavaScript based applications more comfortable you should take a look at TypeScript which makes it possible to write object orientated code that will be “transformed” to valid plain JavaScript (ECMAScript 3 or newer). Especially valuable for guys like me who grew up with C#.
      You can install TypeScript as a Node.js package: npm install -g typescript
    • Yeoman
      Because we won’t use the big and mighty Visual Studio anymore but instead the slim Code IDE it is recommended to take advantage of Yeoman. This Node.js package delivers us thousands of web project templates and acts like a generator to get started with our new applications very quickly and supports us to ensure best practice.
      To install: npm install -g yo
    • Gulp
      Gulp is an efficient build system and acts like the replacement for MS Build (which is not included in Visual Studio Code). This tool will be the last one in our tool chain and will build and deploy our components.
      To install: npm install -g gulp-cli
    • Webpack
      The Webpack Module Bundler helps us to bundle all our web application assets into big bunch bundle. It will be initiated by our Gulp deployment task.
      To install: We won’t install Webpack globally but per project. I will get into detail about that later.

Setting up our first project

So now that we got all our tools together we will create our first project workspace. Just create a folder where you want to store your files. I named that folder MySPFxWebPart. Open a Node.js command prompt and move to the folder. Now we will use Yeoman to generate a SharePoint Framework project template.

For now Yeoman does not include that template locally so we have to install it: npm i -g @microsoft/generator-sharepoint

Installing the Microsoft SharePoint Yeoman template with npm

Installing the Microsoft SharePoint Yeoman template with npm

After that we can start the generation with Yeoman: yo @microsoft/sharepoint --skip-install

The SharePoint Client-side Solution Generator will show up and ask you some questions on how your project should be set up. For now we won’t include any JavaScript framework.

Creating the SharePoint Framework project template with Yeoman

Creating the SharePoint Framework project template with Yeoman

Right after the project has been created we need to run npm install in the local folder to resolve all Node.js package dependencies. This can take a little while.

Deployment to the workbench

When the resolving of the packages is finished you can execute gulp serve to run your SharePoint Framework Web Part directly in a local workbench. How awesome is this?

The SharePoint Workbench

The SharePoint Workbench

In the same time you make any changes to your local files they will be redeployed so you always see the current state of your app in the workbench. To stop Gulp just press STRG+C in the console.

Running Gulp to deploy the Web Part to the workbench

Running Gulp to deploy the Web Part to the workbench

It’s even possible to “inject” your current Web Part into the workbench of your SharePoint Online tenant. Just navigate to your development Site Collection and open the URL like this “https://your-tenant.sharepoint.com/_layouts/15/workbench.aspx”.

Conclusion

So this were the first steps to get into touch with the SharePoint Framework development model. We learned what kind of tools are recommended, how to set up a plain SPFx project and how do deploy it to the workbench both locally and online. You can find a similar tutorial on the official Office Dev Center documentation here.

Also you can dig into great sample Web Parts provided by the PnP guys here. For example this sample Web Part which shows how to handle CRUD operations in different JavaScript framework. The associated YouTube PnP Webcast can be found here – very recommended to dig further.

In one of the next Blog posts I will try to describe some common developments tasks when realizing “real” SharePoint Framework Web Parts. I already got some ideas in my mind. So far, happy coding!

Leave a Reply

Your email address will not be published. Required fields are marked *

thirteen + 3 =