In my last article, Adventures with the SPFx: Part 1 – Getting Started, I covered the basics on how to set up a development environment and how to create your first “Hello World” client-side web part with SPFx so that it can be previewed in both the local Workbench and the Workbench available on your SharePoint Online tenancy. I also pointed out a few gotchas and a great deal of stuff that nobody thought to tell you, so if you are new to SPFx then I recommend that you start with that article first.
In this article I will run through how to package our web part and add it up to a tenancy. As usual, I’ll point out a few gotchas and things that need some more detailed consideration than you might think at first.
So, here’s what I’ll cover off in this article:
- Where to store solution assets
- Bundle and Package the solution
- Deploy the package to the App Catalog
- Adding the client-side web part to pages
- Upgrading and removing the solution
Where to store solution assets
The assets (JavaScript, CSS, graphics and other resources) that need to be accessed by your solution in order for it to function as you have designed need to be stored somewhere. They can in theory be stored anywhere that can be accessed by your solution. This includes a location such as the Site Assets library for your web site as that is generally open to everyone with read-level permissions. This might make sense if what you are doing is developing a solution that is specific to a single site collection when creating a Line of Business (LOB) application for example.
However, of you are creating a solution that has greater utility, such that it might be used in several web sites and site collections then that approach probably makes no sense as you will have to deploy the artefacts to multiple locations. Although, I have seen some solutions where the artefacts are hosted in the Site Assets library of the Root Web of the entire tenancy, so that would be a single place for the entire tenancy – assuming users have read-level access to that location of course.
In general, I think that using a Site Assets library should be avoided as the approach will most likely rely on administrator having to manually upload files to a specific location and so will be error prone and cumbersome to manage. It also allows for the possibility of someone deleting or renaming solution files and folders or changing the access control settings to that some longer have access to the required resources.
Now, as it turns out, every O365 tenancy can be configured to act as Content Delivery Network (CDN) and SPFx provides in-built support to exploit this capability. If you configure your tenancy to provide CDN support then you have a ready-made location in which to host your solution assets which can be relied upon. I’ll explain later how the SPFx instructs your solution to use the CDN of your tenancy later.
Your O365 tenancy will not be configured to provide CDN support by default and you need to run a few lines of PowerShell as a one-time action to make the necessary configuration changes. I covered off how to configure your tenancy as a CDN in my last post and Microsoft cover this more than adequately in the this post https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn, so I won’t repeat the steps here. It’s not difficult, but why they don’t provide a nice easy switch in the Admin Centre is beyond me.
There is another option, rather than using the inherent CDN capabilities of your O365 tenancy, you can choose to store your solution assets on a separate external CDN altogether. If you want to use an Azure CDN then the SPFx can assist with the automated publishing of solution assets there. Microsoft provide another great article on how to configure an Azure CDN for use with the SPFx here https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/deploy-web-part-to-cdn. If you prefer to use a different CDN platform (actually it doesn’t even need to be a CDN, it could just be an accessible location, although CDNs have benefits of scalability, resilience and performance and so it’s generally a good idea) then you will need to upload the solution assets to the right location manually or by some means outside of SPFx.
Setting up an external CDN (in Azure or somewhere else) will add some complexity to your solution architecture and most likely add some costs (CDN services are not generally free for publishers), so why would you bother? Well, this approach is worthy of more detailed consideration because it gives you one huge benefit if you are deploying commercial grade solutions for multiple customers and that is you can potentially upgrade your package from a single location, the external CDN.
Let me explain, if you use the CDN capabilities of your O365 tenancy then the solution package will deploy all the solution files it needs to your tenancy, which is fine – it’s what we expect. But say that solution package has now been installed on 1000 tenancies. If I want to upgrade the solution, to say fix a bug or provide some feature enhancements, then you will have to reach out to 1000 customers and tell them to upgrade the solution. Knowing full well that many of them will never bother. If on the other hand your solution assets are deployed to a single location i.e. to an external CDN then there is a fair chance that you won’t need to reach out to anyone at all. You can just fix the bug or add the new feature and republish. So long as you take great care to ensure compatibility with the previous solution then we are safe. This is an important point because if your upgrade has been inadequately tested you run the risk of breaking all your customers in one go!
I liken this to the differences between the 2 implementations of the Cloud App Model. With a SharePoint Hosted App, your artefacts are stored in SharePoint and so the whole solution needs to be upgraded every time a change is required and you are reliant on administrators to make this change. In contrast, with a Provider Hosted App, you can implement change centrally and effectively take tenancy administrators out of the loop. If you want to up-scale the analogy, you could say that Microsoft has taken this same approach with the continual improvement model they have adopted for SharePoint Online when compared to the step-increases we are faced with by the different versions, service packs and updates to SharePoint 2013, SP2016 and the soon to be released SP2019, on-prem offerings.
For the purposes of this article I am going to use the CDN of my O365 tenancy which I think is just fine for development purposes but later in this series I will come back to deploying my solution assets to a CDN because I think this is the best way to go, if your solution is intended for a mass market.
Bundle and Package the Solution
In the first article in this series, we were able to preview our test web part in both the local Workbench and the Workbench of a remote tenancy, so long as we have Gulp running. That’s fine for testing and basic debugging but how do we get the solution into a form that can be deployed to a live tenancy? Actually, this is quite a simple 2-step process. First, we need to package the solution for deployment and then upload the solution package to the App Catalog of the tenancy in which the solution is to be used.
First make sure that Gulp is not running by issuing a CTRL+C command in the console or command area of VS Code.
Creating the solution package is straightforward enough and requires the execution of the 2 gulp commands sequentially. But before we do that, let’s take a quick look at the package-solution.json file in the config folder of the solution directory, as shown below.
Your package-solution.json file might not look identical to mine as it depends on what you called your solution name – mine was “test-wp”. This file lets you know where the resulting solution package file will be saved and named. Also, notice the “includeClientSideAssets” attribute is set to true. This flag tells SPFx that we are going to deploy the solution assets to the O365 CDN for the tenancy.
The Microsoft official tutorial tells you to run the following command
gulp bundle – -ship
Gulp bundle will generate a release build of the solution and will use a dynamic token to specify the location of your solution artefacts. This token will be replaced with the path to the CDN of the tenancy so that everything can be accessed from your tenancy’s CDN. Note that Microsoft tutorial states that you need append the – -ship (note double dash with no space between them) parameter so that gulp includes all the assets your solution needs. The only problem is that at the time of writing, this throws up an error in the packaging process as shown below:
You can follow the discussion thread on this issue picked up be people far more knowledgeable than I am in this area, but the consensus seems you can run the command with the – -debug instead of – -ship, or just ignore the error and you should be ok.
Next you need to run the following:
gulp package-solution – -ship
Here you do need to – -ship parameter for sure and this command actually creates the .sppkg file which is what we will upload to the App Catalog in just a moment. The .sppkg file is just a .cab file that has been given a different extension so you could rename the file and break into it and see what’s there if you like but actually there is no point because the package-solution command actually added a new top-level folder to you project directory called SharePoint. If you drill into the solution/debug folder then this is the same collection of files which where packaged into the .sppkg file which sits next to that folder at the same level as can be seen below:
So now the solution has been bundled and packaged and is ready for upload.
Deploy the solution to the App Catalog
At the time of writing, there appears to be now way to publish your solution to the App Store or Marketplace or whatever the Microsoft Marketing team choose to call it this month and so we have to manually upload the solution package to the App Catalog of your tenancy.
In O365 your App Catalog will have been already have been created for you and can be found at https://{your-tenancy}.sharepoint.com/sites/appscatalog.
Select the Apps for SharePoint link and then just upload the .sppkg file.
This will likely trigger the “Do you trust…” dialog at which you will need to click the Deploy button.
After which you should see the solution nestling in the App Catalog and reporting no errors.
Adding the client-side web part to pages
Now that our solution is sitting in the App Catalog we can try it out on a page. To do that we first will need to install the app in the site we are using for testing by going to the Site Contents page and then clicking on the “From Your Organization” link, where you should see the solution ready to be installed.
There is actually a way to make an SPFx solution automatically available on all web sites on the tenancy (which I will cover in a later post) but by default we have to manually install it on the sites where it is needed.
Click on the tile to begin the installation process. It may take a couple of minutes to sort itself out but in due course and after a few screen-refreshes you should be able to see it as an enabled app in your Site Contents page.
Now let’s go and add an instance of the web part to a page. So, add a suitable Modern test page, switch to page edit mode and go find your web part. It will be listed in the Others group by default and you might need to click the (easy to miss) “See all” link to locate it.
Alternatively, you can use the search box at the top of the dialog which is generally a much faster method so long as you can remember the web part’s name. Also, be aware that the list of available web parts gets loaded asynchronously and this can take a few seconds and so you may need just a little patience before seeing your web part in the dialog or being returned by search.
Once you’ve located the web part, add it to the page, click Publish and marvel in wonder!
In the above example, I installed the solution and added a web part instance to a Modern Site Page in a site based on the new Communication Portal template. But it is entirely possible to add custom SPFx client web parts to classic pages as can be seen below:
Sadly, this capability only seems to be available for custom solutions so you can’t add any of the out-of-the-box client-side web parts to a classic page. That’s a real shame as it could make the transition to Modern easier for some customers who have to stick for Classic for now
Upgrading and removing the solution
Upgrading the solution is surprisingly simple. Just upload the replacement .sppkg file to the App Catalog, making sure it has the exact same file name of course and select the option to replace the existing file. Note that when you do this the file will be left in a checked-out state and so you need to check in the new file before users can access the new version.
I suspect that the correct way to remove the solution is to:
- Delete all web part instances from any pages on which they are used
- Remove the app from the web sites that are using it
- Delete the .sppkg file from the App Catalog
That seems like a lot of effort and so I wondered what would happen if I just deleted the package from the App Catalog. Well it turns out that SharePoint handles this quite gracefully and web part instances are just removed from the pages automatically.
Actually, I think they are just hidden on the page because in my experience if you re-deploy the solution the web parts seem to be restored
Apps remain behind on the site however, even although they are of no use as new web part instances cannot be added once the solution package no longer exists in the App Catalog. It’s easy enough to remove the app manually and I suspect that if I had been patient enough a timer job might have kicked in and performed some housekeeping. Good job Microsoft!
One other gotcha is that if you try and upgrade a solution which has a version number equal to or less than a previously deployed version of the solution package you may find that you run in to trouble. SharePoint spits the dummy and sends you on a mission to purge your recycle bins (both stages). That gets tiresome if the solution has been deployed to multiple site collections. So much so that you might have to resort to PowerShell. This same thing happens for Cloud App solution packages and so is nothing peculiar to the SPFx.
An easier approach is to get into the habit of incrementing the version number during testing cycles that involve actually uploading the solution to the App Catalog. That way you should be able to avoid wrenching your hair out! I’ll cover off how to increment the version number in my next post.
Talking of which, in the next couple of article in this series, I shall be looking into all those little details that make the difference between an amateur and a professional offering which includes the following:
- Part 3 – Solution Configuration Properties:
- Providing a meaningful title, name and description
- Solution versioning
- Setting the App Icon
- Part 4 – Client Web Part Configuration Settings
- Setting titles and descriptions
- Giving web parts a custom icon
- Placing web part in a different group i.e. somewhere other than “Other”
I feel its important to cover off all the plumbing details before we get on and actually build something useful.
Kaboodle Software 
3 comments