A while ago I did a short series on how to provision and deploy the SharePoint Starter Kit. From this, I thought it would be fun to detail how to take one of the many, great spfx web part samples available in the SharePoint GitHut repository and go through the steps involved to deploy it end to end.
As with my last series on the SharePoint Starter Kit and generally with all my posts my aim is to simplify and detail every step involved to show that you can these things working without huge effort of developer expertise, I am not a developer by any stretch of the imagination so hopefully putting all the pieces together is useful 🙂
spfx client-side web parts
All the samples are available in the sp-dev-fx-webparts repository on GitHub from the link below. For the purpose of this example, I am deploying the Modern Experience Theme Manager web part, as I wanted to test out how easy it makes applying, removing and updating custom themes (it does).
All of the pre-requirement steps detailed in part one of my SharePoint Starter Kit series are also required for deploying web parts. Make sure you have followed all the steps here before continuing:
How to provision and deploy the SharePoint Starter Kit: part one
Before you can begin, it’s much easier to clone a repository from GitHub than downloading and extracting a zip file. I also couldn’t get the web part to open from the localhost workbench when I manually downloaded the code.
You can install github for desktop here: https://desktop.github.com/
NOTE: I originally wrote this walkthrough a while back, when I came to finish it up I tried to update by cloned repo but it just wouldn’t work. I just removed the repo from Github desktop, then deleted all the files from the /sp-dev-fx-webparts/ sub-folder and cloned from scratch and it worked.
Make sure a developer certificate is installed
If you followed my SharePoint Starter Kit series, you can skip this step as you’ll of already done it, but if not run the following to install a dev certificate:
Step 1: get the webpart working locally
Clone repository/ run web part on localhost
Now we need clone and build the repository to start using the webpart sample. Clone the repository by following the steps below:
- Open cmd prompt, then navigate to the samples folder > then the web part samples folder you wish to use for example:
- Run the following command to install the npm packages to build and run the client-side project
- Run the following command to preview your web part in the SharePoint Workbench
Your browser should now open and a localhost version of SharePoint Workbench will allow you to add the web part and access the properties:
NOTE: I tried this using IE at first, it didn’t open at all, so i just switched to using another browser and the workbench loaded just fine.
Test the web part in your tenant workbench
Copy the URL of the localhost workbench, open a new browser window and paste the URL but update it to reflect your sharepoint tenant, for example:
Step 2: package and (soft) deploy!
Package/ deploy the web part to your tenant
Now we have tested our web part is working locally and within the context of our sharepoint tenancy, we can now package our solution and deploy into our SharePoint environment.
- If gulp serve is still running, press CTRL+C to stop it in cmd prompt
- In cmd prompt, enter the following command
- This command creates a package in the sharepoint/solution folder called something like “js-theme-manager.sppkg”
- Navigate to your SharePoint Admin site, open the app catalog site, under apps for sharepoint, drag and drop your sppkg file
- Press the deploy button on the pop-up window, notice the localhost domain is showing here, we will need to change this once we’ve tested our web part is working
- Back to the console, run gulp serve to make the local assets available for the web part
- Navigate to a site where you want to deploy the webpart, press the cog button, add an app
- Select the webpart you just added (this might take a minute or two to be available)
- Add your new webpart to a page!
Enable CDN for your tenant
Now we’ve deployed and tested the webpart in our SharePoint environment, we can update our solution to host the assets directly in our tenancy or a content delivery network .
- Open PowerShell, connect to your SharePoint Online tenant using the following command:
Connect-SPOService -Url https://contoso-admin.sharepoint.com
- Get the current status of public CDN settings from the tenant level by executing the following commands one-by-one.
Get-SPOTenantCdnEnabled -CdnType Public Get-SPOTenantCdnOrigins -CdnType Public Get-SPOTenantCdnPolicies -CdnType Public
spfx solutions can automatically benefit from the Office 365 Public CDN as long as it’s enabled in your tenant. When CDN is enabled, */CLIENTSIDEASSETS origin is automatically added as a valid origin.
- Enable public CDN in the tenant by running the following command:
Set-SPOTenantCdnEnabled -CdnType Public
- Confirm settings by selecting Y and then Enter
Step 3: ready for final deployment
Go back to the console, make sure you are still in the relevant web part project directory, end sure gulp serve by pressing CTRL+C.
- Open explorer, then open the package-solution.json in a code editor, from the config folder and check you see the following:
- Run the following task to bundle the solution:
gulp bundle --ship
- Then, run the following task to package your solution:
gulp package-solution --ship
- From the same sharepoint/solution folder, drag & drop the newly updated solution package into the app catalog again. As it already exists, press Replace
- Check the domain now shows as SharePoint Online, rather than localhost
- Make sure your updated app isn’t checked out, if it is – check it in
- Navigate back to where you previously deployed the app, add it to a page and test that it works!