Getting Started with the SharePoint Framework

Posted by Eric Shupps on Mar 15, 2017 11:34:57 AM

Microsoft recently announced the general availability of the SharePoint Framework, a new development model for the creation of custom solutions within Office 365. The SharePoint Framework, also known as “SPFx”, provides customers with a way to extend the platform for Intranet and collaboration scenarios with a “pages and parts” model that is lightweight and easily configurable. As with any new model, developers will need to learn a new way of doing things, but SPFx has some specific requirements that may prove challenging for those who have been working with SharePoint for any length of time as well as those who are new to the platform. Before getting started, it is important to learn what skills are necessary, which tools are required, and how to configure an environment to begin creating SPFx solutions.

1. Skills:

SPFx solutions are built entirely in JavaScript and HTML and use RESTful API’s to communicate with SharePoint. Unlike add-ins, which can be built in just about any language, compiled or uncompiled, and run on multiple server types, Framework web parts are hosted within a SharePoint page, much like legacy web parts are in the on-premises version; however, the code itself is not actually stored in the content database but rather retrieved from a CDN or other location accessible by the client browser.

Similar in some respects to a SharePoint-hosted add-in, this loosely-coupled integration mechanism means that only uncompiled code is permissible within a Framework web part. Like many other solutions designed for the modern web, the de facto programming language for SPFx is JavaScript, extended via frameworks such as jQuery, React, Angular, Knockout, and so on. For .NET developers moving over from ASP.NET web forms and MVC, this means that a strong familiarity with current web development patterns is a pre-requisite to building SPFx parts and pages. Although knowledge of a specific JavaScript framework is not necessary, a basic understanding of asynchronous, service-based data access via AJAX and the fundamentals of MVC/MVVM are certainly helpful.

One area in which it is essential to have functional knowledge is TypeScript, which is a superset of JavaScript that adds strongly typed, class-based objects for a more controllable and familiar development experience. Although TypeScript is a pseudo-language with its own syntax and structure that must be learned, it compiles down to standard JavaScript that runs in any browser. Due to fixed dependencies within the SPFx toolchain, developers must have at least a functional knowledge of TypeScript programming before attempting to build even simple Framework web parts.

2. Tools:

SharePoint development has always been a balancing act between the extensibility options of the platform and the tools required to effectively take advantage of those options. In the early days of 2003 and 2007 there were a mixture of manual procedures and community-provided solutions that more or less got the job done, but certainly did not provide a streamlined build-and-deploy experience. Things changed dramatically in 2010 when the toolset was integrated into Visual Studio, which made a great deal of sense as all SharePoint projects were essentially ASP.NET solutions comprised of compiled code, markup and XML. Having everything together in a single IDE made it much easier to manage and maintain complex solutions.

With the introduction of the add-in framework in 2013, the reliance on a specific development environment was reduced, as solutions could be built on any platform; although in reality the vast majority were still created and deployed from Visual Studio using the provided Office developer tools. SPFx changes all that, eliminating the need for a commercial IDE and instead utilizing open-source tools for code generation, packaging and deployment. This is partly in response to current trends in the wider web development community, but also reflects differing priorities between the SharePoint and Visual Studio teams, with the former fully focused on cloud-first technologies and the latter required to support a much wider array of legacy and enterprise scenarios.

This means that developers must learn a new way of creating and delivering solutions for SharePoint. Since the underlying language is JavaScript hosted in HTML pages, any modern IDE can be used, from Eclipse to WebStorm to VS Code (or, if you are old school, a plain old text editor), opening up the possibility for Mac and Linux developers to jump in without having to change platforms. Instead of pressing F5 to spin up an instance of IIS Express for local debugging on a Windows machine, an SPFx web part is hosted within a special workbench HTML page running on Node.js, which is a local web server instance built upon a variation of JavaScript runtime engine in Google Chrome. Since it runs on Linux, MacOs and Windows, developers are able to build and test their solutions anywhere and on any machine.

The final portion of the toolchain, and admittedly the most confusing for existing SharePoint developers, is the set of components required to package and deploy solutions so they can be tested within the workbench. For better or worse, Visual Studio obfuscates much of the plumbing required to actually build a WSP package or app file, making it seem much simpler than it actually is (for those who were around in the old days and remember makecab.exe and diamond directive files, this is a welcome improvement). Unfortunately, the open source toolset is not as streamlined, so there will be some adjustment to tools like Gulp (a task runner and build generator similar to MSBuild), Node Packaging Manager (NPM), which handles the vast array of project dependencies, and the project artifacts required to get everything working the right order.

3. Environment:

For developers who have never built an open-source JavaScript solution the departure from the friendly confines of Visual Study may be startling. The challenges start with just getting a basic development environment set up, which requires the installation of all the required tools and likely a few others, such as NVM to manage multiple versions of Node.js, Homebrew if you are working on a Mac, and, of course, the Yeoman generator, which contains the project templates for building SPFx web parts. And all of this is done from the command line with no GUI components whatsoever.

Assuming setup happens on a clean machine with no previous versions of the tools, following the Microsoft documentation should be a fairly straightforward process; however, if things go awry or if previous versions of any tools already exist, sorting out the dependency conflicts can be a time-consuming and frustrating task. This, unfortunately, is the state of things for many non-Microsoft developers and something the SharePoint development community will simply have to accept until such a time as the toolset changes or new processes become available.

Once the environment is in a functional state, the Yeoman generator can be launched and a new project created. Developers should ensure they have plenty of disk space for building and testing SPFx solutions as the toolset creates a full copy of everything the project depends upon in the target directory. This can result in hundreds of megabytes for even the simplest of “Hello, world!” web parts. Fortunately, this is only a development issue, similar to how Visual Studio installs gigabytes of stuff that few people actually ever use, as the final package that gets deployed to the CDN is quite small.

Testing in the Workbench is a nice feature that removes the need to constantly redeploy everything to SharePoint for iterative debugging, although once the API’s are invoked for data exchange it is better to have the web part on an actual SharePoint page. This is where additional tools like Fiddler, Wireshark and browser-based development utilities can aid in the debugging process. For source control, Git (and the public/private hosted repositories on GitHub) is the tool of choice for most web developers. There are client tools (and even a GUI for Windows) that can be installed on every platform and some IDE’s also offer direct Git integration. For those running Visual Studio on Windows to manage project structure and code editing, TFS remains a viable option with or without Git integration.

As the latest and most cloud-focused of the various development models, the SharePoint Framework will be receiving a lot of attention going forward. Developers who wish to adopt SPFx as part of their overall extensibility strategy for SharePoint will need to learn some new skills, adapt to a different set of tools, and ensure they have a properly configured environment to take advantage of the new model. Although it may initially create some challenges as the community adapts to a new way of doing things, in the long run the greater the adoption the more likely the possibility of future improvements and the more resources Microsoft can dedicate to providing enhancements.

Eric Shupps is a SharePoint Server MVP, and the founder and president of BinaryWave, a global provider of SharePoint managed services. He will be presenting developer-focused sessions at SPTechCon Austin, April 2-5.

Topics: SharePoint Framework

Thoughts? Leave a comment: