SharePoint Framework (SPFx) enterprise guidance
The SharePoint Framework (or SPFx) is a new development model for SharePoint user interface extensibility. It is used by 1st and 3rd parties, complementing already existing user interface models such as the SharePoint Add-in model. The SharePoint Framework allows for a structured and supported approach to enrich and extend the user interface of SharePoint, using client side frameworks with initial support for client side Web Parts. Based on modern web technology standards, it offers a unique set of features to make SharePoint customizations more broader available for developers and enterprises, but at the same time aligns with previous models and patterns in SharePoint. In this document, we will provide administrators with the background, benefits, and knowledge they need to successfully manage SharePoint Framework-based components within their SharePoint environments.
Current status of SharePoint Framework
The SharePoint Framework reached the General Available (GA) milestone, with version 1.0.0, in February 2017.
From a developers point of view
SharePoint developers, new and seasoned, all have something to gain from the SharePoint Framework. While the current release is focused on the user interface extensibility story it allows the developer to, in a safe and structured way, extend the user interface capabilities of SharePoint using, initially, client side Web Parts. These Web Parts are executed client side and can work with data in SharePoint, in Office 365 via the Microsoft Graph or even using your own custom Web APIs using standard OAuth and REST methods.
For developers that have never built SharePoint solutions previously, but are familiar with modern web technologies, the threshold is not that high, and many developers have already moved to the client side of development, or a combination of it. Client side development can provide a better, more dynamic and more responsive experience for users and even an easier experience for developers. Thanks to the freedom of code editor, the use of well-known and popular open source frameworks and technologies, many developers that might not even at all has worked within the Microsoft eco system can easily get up to speed on building SharePoint extensions.
In Perspective: SharePoint Framework in the Broader SharePoint Platform
The SharePoint Framework is a new model, additive to already existing methods, but focused on leveraging more value to user interface customizations such as client side Web Parts. This framework is designed to work in conjunction with already existing working models and but also to make it easier to create new user interface customizations in a more supported and sustainable way.
Compared with Add-ins
The SharePoint Framework works side by side with both SharePoint hosted and Provider hosted Add-ins, but can also be used as an alternative in scenarios where only client side scripting is required. For instance, Add-ins can add App Parts to the site where they are hosted. These App Parts are similar to Web Parts, but instead of running in the context of the page, they run in their own domain (App Web or Provider hosted web) within an Iframe on the page. This prevents the Add-in from gaining the user context from the rest of the page. The SharePoint Framework, on the other hand, does not run in an Iframe. Thanks to this, it can more seamlessly run in the context of the page with the full power of the user viewing the part. This is they key to enabling it to run with rich functionality, but at the same time means that it does not have the same level of security controls as Add-ins. SharePoint Framework solutions are due to this also being referred to as full trust client side solutions. Also Iframes suffer from the problem that they are not responsive which will result in that the rendered web page will not be as fluent on a mobile phone, or alternate screen size.
The SharePoint Framework solutions does not, at the time of writing, have a store where you can download and install solutions, due to the security aspect mentioned above. On the other hand in many scenarios using the users context is a wanted scenario - where SharePoint Framework could be used instead.
Script Editor Web Parts
Control of scripting capabilities in SharePoint Online
SharePoint Online allows the admins to control the ability to add custom scripts to sites and pages, to increase the security and integrity of the tenant. This is done using the "Custom Script" feature in the SharePoint Online admin site, or individually per site using PowerShell. Custom scripts can be disabled on all sites or just on personal sites. By default, new tenants have scripting disabled on Personal Sites, all self-service created sites, as well as the root site collection of the tenant. When custom scripts are disabled, editors of sites are not allowed to add web parts such as the Script Editor Web Part. However SharePoint Framework solutions are allowed, since they are considered safe after being approved by an administrator in the App Catalog.
Differences in how SharePoint Framework Solutions are created – and why it matters
The SharePoint Framework uses a new paradigm to SharePoint developers in how to design, build and deploy SharePoint customizations, by leveraging a modern web stack approach and focusing on client side/browser based customizations. This marks an important change in how SharePoint development is being treated. By using technologies and frameworks such as TypeScript, Node.js, Yeoman, Gulp and more the SharePoint Framework hopefully will attract developer audiences that traditionally not been in the SharePoint, or even Microsoft, eco-system. But also at the same time open up for existing SharePoint developers to build SharePoint customizations using a more modern and standardized approach.
Because of the need for very specific and targeted tools provided via Visual Studio, SharePoint Development was typically solely done via Visual Studio on a Windows machine with an instance of SharePoint installed and running, which severely limited the hardware and user preferences, and increased development costs. The SharePoint Framework, on the other hand, uses various common open source web tools available for a number of different platforms, like MacOS and Linux, to allow for more flexibility in development.
SharePoint Framework solutions are created using a tool called Yeoman along with a specific SharePoint Framework generator, which is based on Node.js. Yeoman is a project scaffolding tool and will create your project and generate the required artifacts, install the needed Node.js packages and configures the build system. Once the project is generated it can be edited in any editor on any operating system; Visual Studio, Visual Studio Code, Sublime or Atom for instance. This allows for a wider usage preference and style, in and between teams. The Yeoman generator can be run multiple times on the same project in order to add additional artifacts, such as client side web parts.
Developing and building solutions
The build system is based on Gulp which is a task runner that builds, packages and optionally deploys the SharePoint Framework artifacts. Like Yeoman, Gulp is also based on Node.js and allows developers to build and deploy on any operating system. One big, and new, part of the build toolset for SharePoint Framework is called the Workbench. The Workbench is a tool where the developer can host and test their SharePoint Framework solution. The Workbench are reactive and will automatically reload your artifacts when the developer saves a file so that developers can see and test the solution in a fast paced way. There are two version of the Workbench, one outside of SharePoint hosted locally on the development machine that runs 'offline' without SharePoint access and SharePoint data. This allows the team and designers to build and design solutions with mock or fake data to focus on the user interface. The second version is hosted inside SharePoint and are to be used when you need to test and verify the SharePoint Framework solution using real SharePoint data and context.
Deploying SharePoint Framework solutions
Deploying SharePoint Framework solutions are done in two steps; the first one being deploying the script artifacts packaged by the build process to a CDN (Content Delivery Network) location. The second step is to add the solution package to the App Catalog and approve it for usage in your tenant. The package added to the SharePoint App Catalog contains a pointer to the CDN location.
Developers of the SharePoint Framework solution can choose to use any CDN service; such as Azure Storage, Azure CDN, or even SharePoint itself, preferrably using the SharePoint CDN features (see below). Using a public CDN, where the assets deployed to the CDN are publicly available on Internet, allows for usage of the SharePoint Framework solution to be used by many tenants. In a SharePoint CDN deployed SharePoint Framework solution, the deployed scripts and resources are only available for the tenant it is deployed into.
By default, there is a built-in task in the build tools to deploy the packaged solution to an Azure Blob storage. This is something that is typically extended, by SI's or ISV's, to support custom CDN locations or configurations.
After changing the code and building the solution, the SharePoint Framework toolchain produces a new solution package (.sppkg) and a set of script files. These script files include a unique hash in their filename, which indicates that the contents of these files differ from their previously deployed versions. To use a new version of the solution, you have to deploy the new set of scripts to your CDN and update the solution package in the App Catalog. While theoretically, you could replace the contents of the existing script files and avoid upgrading the solution package, it's unreliable and not recommended. Depending on the configuration of your CDN, it could be that the previously downloaded script files are cached for a long time on the client computers, complicating the rollout of the solution to end-users.
The location of the CDN is of importance. The location where the SharePoint Framework assets are hosted must have high availability, so trusted CDN providers such as Azure, Akamai or similar, and SharePoint itself, are recommended. From a security standpoint it is important to know what CDN's are in use by the SharePoint framework solutions deployed. A broken CDN can also break the SharePoint Framework solutions, and in worst case a compromised CDN might lead to that the data in the SharePoint (Online) tenant also being compromised.
When approving third party SharePoint Framework solutions, a typical checklist item is to check the authority and trust of the CDN location and any third parties that might host them. This is because once the application is installed and used within SharePoint Site collections, these site collections will have a dependency on the CDN location. As of this writing, there is no easy way to to control that end-point. The third party provider of the CDN can update with both wanted and unwanted changes without the users knowledge opening up an attack surface, given that the SharePoint Framework is running under the users context and can do whatever the user are allowed to do.
A recommendation is for IT administrators to keep track of what CDN's are used, and what CDN's are approved by the organization - which should also be communicated to the enterprise developers.
Office 365 Public CDN
Administrators can enable the Office 365 Public CDN capability on one or more designated document libraries, which will serve as the origin for the static assets. Administration of the libraries and the CDN are done using the SharePoint Online PowerShell cmdlets. The assets, in the document library, will be replicated to the Office 365 CDN and be accessible through the Office 365 Public CDN URLs generated and associated with the document library. Any updates to the assets will be reflected on the CDN end-points within 15 minutes. Note that any assets within the document libraries will be available for anonymous users, through the CDN end-point.
SharePoint Framework in the enterprise
SharePoint is and have been one of the most successful enterprise collaboration platforms and one of the reasons to its success has been the possibility to extend SharePoint and consider it as a platform for applications and integrations. The SharePoint Framework will further expand this success by making SharePoint a more modern platform to build client side customizations on top of in a supported and standardized way.
The SharePoint Framework allows Enterprise developers, typically a developer that creates application for use within an organization, to extend SharePoint (Online) with new functionality in a structured and supported way. The SharePoint Framework offers everything from the development framework, build pipeline, to the actual deployment and allows the developers in a short time reach out to all Site Collections with new solutions and features, all controlled by the App Catalog. In an enterprise scenario you also have full control of the CDN locations; external or internal in SharePoint and you can very easy deploy fixes and updates to your whole organization.
Within your enterprise administrators and developers jointly should create a blue print for how SharePoint Frameworks solutions should be deployed. The blue print should contain details on preferred client side frameworks, CDN locations etc. For more details, see the section below on Building a plan around SharePoint Framework customizations.
User experience designers and front-end developers
For web developers or user experience/interface designers the SharePoint Framework will be very valuable. The Workbench allows front-end developers to work with a SharePoint Framework solution on any operating system and using their preferred editing tools without SharePoint, given that they use mock data, and focus on the user experience. The SharePoint Framework is released in parallel with Office UI Fabric, which is the official front-end development framework for Office and Office 365, and allows the user experience designers to create a seamless experience across Office, Office 365 and the custom built solutions.
System Integrators (SI)
If you leverage System Integrators (SI) or consultancies to build your SharePoint and Office 365 solutions you should place recommendations, or even requirements, on how they should build SharePoint Framework solutions so that it is aligned with your enterprise plan for the SharePoint Framework. Typically System Integrators have a preferred way of building their solutions, which might not always be aligned with your governance, so this discussion with the System Integrators is important and will in the end make it easier for all parties. A typical scenario with System Integrators is that they build the solution for your company and after the project is complete it is up to you to maintain, upgrade and update the solution, which only emphasizes that you need to align with the SI on how the SharePoint Framework solutions are built and hosted.
Independent Software Vendors (ISV)
Independent Software Vendors (ISV) are organizations building third party solutions for the mass market and they might not always fulfill your plan on SharePoint Framework solutions. Also ISV's typically own their own code and intellectual property which makes it very hard for you to change the way they implement and host their solutions. In the case of using SharePoint Framework solutions from third party providers you need to specifically look into how they manage updates and how their solutions are hosted. For instance; Do you allow the solution to be updated without your knowledge? Do you allow the static assets to be hosted on the ISV's CDN without your control? What is your trust relationship with this ISV? Remember that any client side code in SharePoint Framework executes under the current users context and there is no possibility for you to put constraints on that, which you can do with SharePoint Add-ins.
Building a plan around SharePoint Framework customizations
Developers might want to standardize on one specific client-side framework for the organization or if even standardize on different frameworks. Client-side frameworks include, but are not limited to, React, Knockout, Angular, Handlebars, jQuery etc. There are advantages on standardizing on one framework, since that enables developers to build more reusable code and have better consistency in how they build and maintain their solutions. On the other hand, there are advantages of allowing more than one framework since each client-side framework has its pros and cons and use cases. But, allowing any client-side framework may cause fragmentation in your enterprise solutions, not to mention having multiple different frameworks might add to the page load time, since many frameworks requires loading of more external libraries.
Out of the box, the SharePoint Framework Yeoman generator has templates for two client-side frameworks: React and Knockout. Over time one can expect that the community adds more generators or sub-generators to use other client-side frameworks. Choosing React as your preferred client-side framework has an advantage due to that Microsoft has created a React version of the Office UI Fabric, so you will get the Office and Office 365 look and feel of your customization, if that is something your organization prefers.
The fourth thing to plan for is how and where you deploy your solution artifacts, that is in what CDN are your generated script bundles and assets stored. Out of the box, in the Gulp tasks included in the tool chain, only Azure Blob storage and Azure CDN is supported. This might be a very good option if you can manage an Azure subscription and also require to share your assets between multiple tenants. Another very common scenario is to use SharePoint Online, and its CDN feature, as a host for the artifacts. This however requires you to modify the tool chain and optionally create custom Gulp tasks to manage.
Finally, developers will need to think about application life cycle management (ALM). The way you manage source code and versioning, automatic build, testing and deployment etc. Most common source code versioning systems can be used such as Git, Github or Visual Studio Team Systems. For continuous integration there are no default tools and you can use your tool of preference that supports node.js, such as Visual Studio Team Systems, Travis CI, or Jenkins. Using these tools you can automate the build and testing process and in the case of a successful and approved build you can even automatically deploy the artifacts to the CDN location, and in such way automate everything from the developer checking in the code to deployment to production.
Management Capabilities of SharePoint Framework solutions
All SharePoint Framework solutions deployed into a tenant must be approved by a tenant administrator. This is done by uploading the SharePoint Framework package, the
.sppkg file into the Apps for SharePoint library. When a new solution is added to the library, the administrator will get a dialog that asks for a consent to approve the solution for use in the tenancy. The dialog explains that this is a full trust client side code solution without any resource restrictions and that it executes under users context. The dialog also shows from what domain it will primarily get content, that is the CDN location of the SharePoint Framework scripts. Note that any SharePoint Framework application can load data from other locations, after the initial load from the CDN. Once approved the SharePoint Framework solution can be enabled on any Site Collection.
An administrator of the App Catalog can at any time remove the package from the App Catalog by removing the solution package from the Apps for SharePoint library. This will prohibit the solution to be used in all Site Collections. The solution can also be disabled by modifying the Enabled property of the uploaded package. This will immediately disable the solution in all Site Collections; existing pages using client side web parts will not render the web part and the app will not be available on the Site Collections or available to add on existing Site Collections. When removing a SharePoint Framework solution it will not remove any data or information created by the actual client side solution either in SharePoint or in any external data source used by the solution.
The administrator can also modify other properties on the package in the App Catalog in order to enhance the visibility of the solution in the Site Collections; for instance, the icon, category, description and the featured status can be changed.
If there is a need to update the solution package, which are required if new SharePoint Framework artifacts or other package level changes are made, then the administrator only need to upload a new version of the package to the library.
A tenant admin can also monitor the SharePoint Framework solutions, just as with SharePoint Add-ins. In the SharePoint Admin center under apps the SharePoint admin can add the SharePoint Framework solutions and then see how many installed locations there are of a specific solution, for both SharePoint Add-ins as well as SharePoint Framework solutions.
To enable a SharePoint Framework solution on a Site Collection, the Site Collection administrator must add it to the Site Collection. This is done in the same way as for SharePoint Add-ins, by selecting to add a new Add a new app on the Site Collection, then choosing the solution from the list of apps. Once the app is added it is available for use in the Site Collection. The Site Collection administrator can also remove the SharePoint Framework from the Site Collection. This is done by going into Site Contents and then choose Remove on the app.
SharePoint Framework Deployment Scopes
When building SharePoint Framework solutions, developers can choose whether their solution supports tenant-wide deployment or if it has to be deployed on each site separately. The latter is required, when the solution needs to provision additional resources, such as lists, after being deployed to a site.
While the developers building the solution decide if the solution supports tenant-wide deployment or not, it's the administrators who make the final decision how the solution is deployed. Even if a solution could be deployed to all sites in the tenant, administrators can choose to deploy it only to the specific sites. If the solution doesn't support tenant-wide deployment, then administrators can deploy it only to specific sites.
Important: tenant-wide deployment is available only in SharePoint Online. In SharePoint hosted on-premises, SharePoint Framework solutions can de deployed only to specific sites.
The SharePoint Framework does not have a store, which SharePoint Add-ins have. For this reason, any deployments always must be initiated by the tenant admin by adding and approving a solution package to the App Catalog.
Backing up and restoring SharePoint Framework components
SharePoint Framework solutions does not have any specific backup and restore features. The only thing that is recommended from an administrative perspective is that it might be a good idea to have a copy of all installed solution package files (
.sppkg), if a solution package is by mistake removed from the app catalog. However, the app catalog is a SharePoint library and have the same capabilities as any document library, with major versioning turned on and the recycle bin.
What you cannot backup is the actual solution artifacts such as script bundles and assets, that are hosted in a CDN. However, if you have control of the CDN or the CDN is a SharePoint site you can back them up. On the other hand, if you are using SharePoint Framework solutions provided by a third party, there may be no way for your organization to back them up.
SharePoint Framework Roadmap
The SharePoint Framework reached General Availability (GA) in February 2017. General Availability means that IT and developers can use SharePoint Framework in production in a supported manner. Beyond General Availability, we would expect that the set of scenarios where we would see SharePoint Framework-based components are built and used will expand beyond web parts scenarios, and into areas like list and site customizations. For more information about the SharePoint Framework see the dedicated SharePoint Framework Roadmap article.
Major changes or introduction of new major features will be announced through the Office 365 Message Center, found in your tenant admin - something that an Office 365 administrator already should have on their daily routine to check. Another important resource is the Office Developer blog where you will find even more details and updates.
The SharePoint Framework is a great new addition to and evolution of the SharePoint customization toolbox that allows developers to extend SharePoint in a supported and controllable way. SharePoint Framework, based on open source and modern technologies, lets developers extend your SharePoint enterprise development story to not only the SharePoint team, but can include a more diverse set of developers. As an administrator, providing proper governance and support for SharePoint Framework within your tenancy can empower your developers to build more engaging solutions more quickly, resulting in better efficiency all around.
Since the SharePoint Framework is created for first and third party developers, and in growing use by Microsoft for future feature enhancements of SharePoint, it is also a safe bet for your organization. We can expect to see incremental updates and additions to the SharePoint Framework over time to close the feature gap between the classic SharePoint and the modern SharePoint experience.