Notes from the Field: The SharePoint Framework

So, by now you should have heard the SharePoint Framework is now available within Office 365, as it hit GA the other week. This is a big milestone and one that we should all take note of now. 

However, my experience has always been that for most organizations, no one is truly ready to utilize a new component, service or adopt a change when it launches. This is often because the effort needed to get everyone up to speed, is often outweighed by the current work that needs to be completed. As such we often find or ourselves becoming masters of searching the internet, trawling through Google or Bing results hoping that someone else has hit that issue of wrote a blog post about it. The good news though is that Microsoft have done a pretty decent job of documenting most things that you could face or need to know for the SharePoint Framework, however not everything is covered.

As such I wanted to talk about something that we all need to cater for when designing solutions using the SharePoint Framework. This is the structure of the code that we write, especially the existing JavaScript or client side code solutions that we need to migrate over.

When writing JavaScript code, there are three trains of thought on how to write it. The first is Asynchronous Module Definition (AMD) pattern. This code is very simple and logical in its approach, allowing us to define functions, and expose methods that can be used across our code. An example of AMD code could be:

Now if we wanted to do create the same code using the second pattern which is CommonJS, we would need to change it slightly. If you have written any code for Node.js for example then you normally use this approach.

Lastly, we could write the code in Universal Module Definition (UMD) format. This is becoming more popular and if you look at some of the SharePoint Framework core code, it follows some of this pattern.

Each type works, each time performs the same task, but each one has its own merits. When coding for a SharePoint Framework web part, the pattern you will be following is for me personally a mix between using CommonJS and UMD syntax. As an example, including jQuery within a SharePoint Framework web part requires not only the references to the code, but also it will need to be specially includes in the web part code.

As you can see, we need to “require” is which comes from the CommonJS model and then we import into a core object which follows the UMD pattern. Using external libraries that are not written in the newer formats can be a bit complicated too, within the SharePoint Framework, purely based on how functions are called and used. If we wanted to link to an external file within the framework, there are two ways of doing it, based on the version of the JavaScript is written in.

Firstly, all external JS links need to be added to “config.json” in the project. Within that file is a section called “Externals”, this is where those external JavaScript references should go. Whether the URL is external to the solution, or you have copied them into the source folder the syntax is still the same.

Notice that because these files are not written in the newer UMD format, that we must reference this in this way, setting the code name, path and global name that we then use within the import statements in the web part. If were adding a newly defined UMD module we could simply reference it this way:

As you can see this can make it very confusing when trying to convert existing code into SharePoint Framework ready code. Of course, we don’t really want to refactor all the code, but my suggestion would be to maybe look at that as part of the task, the same as you would do if you were converting a full trust SharePoint solution to this new framework. To help you in referencing external files correctly, the amazing guys of at Rencore just realized a tool that can be used, you can read more about it here: https://rencore.com/blog/correctly-reference-scripts-rencore-script-check/

The real goal here is to really think about the solutions you are making and probably refactor to make the solutions module based which will follow the pattern found in the core SharePoint Framework. 

To help you understand how to refactor I would suggest some of the following resources and examples: