In the last Notes from the field, I talked about the JavaScript construct needed for the SharePoint Framework. In this post, I want to talk about the end of the process, we have built a super cool web part or control and now need to get this into SharePoint Online.
Luckily the whole construct of the framework is built on the idea of automatic tasks that can be defined and used to not only compile but produce the final Web Part package file needed. Once you have a project created you can then run gulp commands to compile and build the code. In reality what happens is everything gets minified and combined using the web pack components.
Before we start I am using the following versions of the components:
Running “gulp --ship” will build everything that is needed and return the complication tree confirmation within the console.
Going back into our editor, for this I am using Atom or it could be vscode or any number of editors, you can now see a new folder called “temp” that is now created and populated. Expanding the “temp” folder displays a “deploy” that contains the newly compiled files.
The location for these files to be stored after generation is controlled by the file named “prepare-deploy.json”, this contains the property “deployCdnPath” which is set to that location.
This can be changed if needed, for now we will leave it the as the default. Now what the ran gulp command does is only produce the files needed that have to be hosted somewhere, it does not however create the SharePoint package that needs to be deployed. To do this we can use “gulp package-solution”. Once completed you are then displayed the full package output in the console.
Going back into the editor we can now see another folder is created called “sharepoint”, yes, it is lowercase with no capital letters anywhere, before anyone tries to correct my spelling.
The most important new component created is the “.spapp” file that is the piece that needs to be deployed into your App Catalog within your SharePoint Online site.
Now that we have this, in reality the next few steps are to copy the components to where they need to be, but before we do we need to define the final “cdnBasePath” and recompile so everything references everything correctly. Modify the file called “write-manifest.json” and simply put your SharePoint Online location that you are going to store your supporting files into.
In my site, I just added a folder in an assets library for my assets, obviously, there are better ways of doing this like using a real CDN not my SharePoint site, unless you are using the new Azure / Office 365 CDN component.
Next you will need to follow the steps in my previous posts on setting a CDN within Office 365.
The final value should be something like this, which is the public CDN URL not the direct SharePoint URL for the location you are using.
https://publiccdn.sharepointonline.com/{tenant}.sharepoint.com/{CDN ID}/
https://publiccdn.sharepointonline.com/mytenant.sharepoint.com/1678007124ccf82b8f38f36556fac3fd33a5ab7a97bae9a7516e88de8282039b1345c2ec/
Now you need to run the “gulp bundle --ship” then “gulp package-solution --ship” commands to regenerate everything with the right references. Next, we upload the files from the “temp/deploy” folder to the SharePoint location.
Now that we have the supporting items, we can now browse to the App Catalog for our site and upload the “.spapp” file. When prompted after uploading ensure that the settings are correct for the “deploy” window.
The URL listed should match the CDN URL that was added to the “cdnBasePath” within the file called “write-manifest.json”. Now you can go to one of the site collections and choose the “Add an App”, then select from “Apps from your organization” and select the application. You can then modify a page and add the new web part.
If you receive an error at this point, check the URL, rebuild again, deploy again and then test. You might of course wonder how we can fully automate the deployment process, if so then you can look at “gulp-spsync” by Wictor Wilen which can be found in GitHub here or you could look “gulp-propellor” and “gulp propeller-sharepoint”, which can be found here and here. These extend the “gulp” process with extra tasks that can be run during the compilation process.
