SPFx Deployment & Upgrade

Package SPFx Solution

SPFx has greatly simplified the packaging and deployment of solutions. Post completing your SPFx solution development you can creating the SPFx package (.sppkg) by executing two simple commands:

1. Gulp bundle
2. Gulp package-solution

You can execute these commands from the Visual Studio Code Terminal. Click Terminal in the Menu bar and select ‘New Terminal’.

Gulp bundle – The gulp bundle command will generate the debug bundles for your solution. This would basically, convert the TypeScript files to JavaScript to be understood by the browser and generate the required configuration files. You can also use gulp bundle --ship to generate bundles in release mode. The '--ship' operative would indicate that the solution is ready for release.

Gulp package-solution – The gulp package-solution command would collect all the JS and configuration files generated by gulp bundle into an SPFx package. It would create a .sppkg file that can now be uploaded to the SharePoint App Catalog for deployment to the site. Similar to the gulp bundle command we can use the '--ship' operative for package-solution as well to package the solution in release mode. The command would be gulp package-solution --ship.

In conclusion, the commands for packaging the solution in debug mode are:
gulp bundle
gulp package-solution
And the commands for packaging the solution in release mode are:
gulp bundle --ship
gulp package-solution --ship

Please note: The .sppkg file packages all the SharePoint assets and Client-side assets of the SPFx solution. These assets would be hosted in a CDN defined in the write-manifest.json file’s “cdnBasePath” parameter. If you are looking to host the asset files in a pre-defined CDN location, you need to specify the location in the “cdnBasePath” of write-manifest.json file. Else, if a CDN is not specified, SharePoint will create a local CDN in the App Catalog and host the asset files. You would need to define the CDN path before bundling and packaging the solution.

Default CDN:

Custom CDN:

Upload and Install Solution to SharePoint

Once you run the gulp package-solution command the SPFx package file (.sppkg) is created. This file is located in the SharePoint --> Solution folder of your main folder. The file name can be modified from the package-solution.json file in the ‘Config’ folder. The ‘solution’ tag in the file defines the details of the package file created.

You can modify these details and execute the bundle and package-solution commands again.

To apply this package to our SharePoint site you need to:

1. Provision App Catalog – The App Catalog can be provisioned at a tenant level or site collection level for SharePoint Online. For SharePoint on-premise the App Catalog can be provisioned at a web application level or site collection level.
1. App Catalog at Web Application Level – You can create an App Catalog and associate it with a Web Application for SharePoint on premise by browsing to the Central Administration site --> Browse to ‘Apps’ from the left navigation --> In the screen that appears select ‘Create a new App Catalog site’ and provision your app catalog.
2. App Catalog at Site Collection Level – You can provision an App Catalog for your Site Collection by running the following commands:
3. SharePoint Online – Start SharePoint Online Management Shell and execute the following commands:
   Connect-SPOService -Url [Your SharePoint Admin Site URL here]
   $site = Get-SPOSite [Your Site Collection URL here]
   Add-SPOSiteCollectionAppCatalog -Site $site 
   
   SharePoint On-Premise – Download and install the PnP SharePoint Powershell commands and execute the following commands for your site:
   $site = Get-SPSite [Your Site Collection URL here]
   Add-PnPSiteCollectionAppCatalog -Site $site
   The site collection App Catalog will be available in the Site Contents page of the root site of the site collection. It will be named ‘Apps for SharePoint’.
   
2. Upload the .sppkg file to the App Catalog – Upload the .sppkg file from the Solution folder to the SharePoint App Catalog. On uploading the solution, a dialog will be displayed to deploy to the solution to SharePoint site. Click ‘Deploy’.
   
   
   
3. Add the web part to the site – Navigate to the site contents of your site and click ‘New’ in the top ribbon. A popup menu appears, select ‘App’.
   
   
   You can now select the App you have installed and add it to your site collection. If your App contains an extension the customizations will be directly applied to your site. If your App contains a web part, you will now be able to add the web part to the SharePoint page.

Upgrade SPFx Solution

In case there are any changes to your deployed solution that you would like to release as an upgrade, you can follow the below steps to upgrade the SPFx solution.

1. Re-package the Solution – You would need to change the version number and rerun the packaging commands to re-package the solution.
1. Open the ‘package-solution.json’ file in the ‘config’ folder.
2. Update the version number for the solution parameter and save the file.
   
3. Re-execute the gulp bundle --ship and gulp package-solution --ship from the terminal as done during solution packaging.
   Please note: Changing the version number to a new incremental number (major version or minor version) is mandatory to allow us to upgrade the application.
   
2. Upload the Solution to SharePoint – Post re-packaging the solution the .sppkg file will be available in the sharepoint --> solution folder. You would need to upload the file to the same App Catalog. A popup will appear asking you to “Replace the file” or “Don’t upload”. Select the “Replace the file” option and check-in the solution file.
   Please select the solution and click “Deploy” from the “Files” tab in the top ribbon, if the app is not automatically deployed.
   
   
   
   Please note: the “Deploy” button will be disabled if the app is already deployed. In case, it is disabled you can continue further.
   
3. Upgrade the Installed SPFx Solution – For upgrading the solution:
1. Browse to the Site Contents page of the site.
2. Click on “Return to Classic SharePoint” below the Quick Launch
   Please note: If you are unable to see the “Return to Classic SharePoint” button you can simply try to delete your app. It should take you back to the Classic SharePoint UI.
   
   
   
   
   
3. In the classic SharePoint UI click on the ellipsis beside your app and click 'About'.
   
   
4. In the popup screen that appears you will find the following message: A newer version of this App is available followed by a “Get It” button. Click on “Get It” to upgrade your App.

SPFx Solution Components

Scaffold your SPFx Solution

Run Command Prompt as Administrator and execute the following command to scaffold your SPFx Solution -
Please note: If you have installed the NodeJS components globally (as system administrator), you can execute the commands from any folder. However, in case you have installed the NodeJS components without administrator privileges, you would need to execute these commands from the local folder where node modules are located.

1. Through Command Prompt, browse to the folder where you would like to create your solution
2. Run yo @microsoft/sharepoint
   Please note: the @microsoft/sharepoint generator command would require you to install the SharePoint generator through npm. You need to execute npm install @microsoft/generator-sharepoint -g (‘-g’ switch would install the generator globally, do not use this switch if you would like to install the generator in the local folder only)
3. A list of questions would be posted to you to enable the generator to scaffold the solution accordingly. They are:
1. What is your solution name?
2. Which baseline packages do you want to target for your component(s)?
   Ideally, SharePoint Online only (latest) would provide you with the latest SPFx framework and components, however, if you are planning to install your solutions on SharePoint 2019 on-premise then you would have to select SharePoint 2019 as the option here. There are specific settings for 2019 solutions which are not available on SharePoint Online.
3. Where do you want to place the current files?
   You can place the files in the current folder OR create a sub-folder with the solution name. I would prefer creating a sub-folder as this would group all my project files together instead of them lying all around in a used folder. It would also help you open the source folder using an editor like Visual Studio Code.
4. Do you want to allow tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment?
   The SPFx solution is deployed to a SharePoint site using the Feature framework. The activation or de-activation of the feature would make the solution available or remove it. If you answer ‘Yes’ here, the feature implementation step would be skipped, and the web part/extension would be available to all sites in the tenant on installation. However, if you have certain SharePoint artefacts to be deployed, you would need to answer ‘No’, as those would mandate the feature installation step. In my view, the feature installation step allows more control to administrators to enable/disable the SPFx solution.
5. Which type of client component to create?
   Web Part or Extension (In case you select Extension, it would as you for the type of extension) 
6. What is your Web Part/Extension name?
7. What is your Web Part/Extension description?
8. Which framework would you like to use?
   I would prefer ‘No JavaScript framework’ as this would allow the flexibility of adding components I need later.

Please check the screen-clipping below with a sample set of answers:

Post this the solution would be scaffolded and available at the location specified.Post this the solution would be scaffolded and available at the location specified.

Open the Solution with Visual Studio Code

Post scaffolding a directory with the solution name would be created.

1. You can start Visual Studio Code (Right click  Run as administrator). 
2. From the ‘File’ menu select ‘Open Folder...’.
3. Browse and select the folder where the solution was scaffolded.

The solution files should appear as below:

Significant Components of SPFx Solution

Certain key files and components of the SPFx solution (refer image above) are listed below:

1. Config folder – contains the configuration related files for the solution
1. Config.json – Primarily defines the entry point and manifest files of the solution. You would not need to make any changes to this file
2. Package-solution.json – Defines the features of the .sppkg file that will be created when the solution is prepared for deployment. Key elements such as package file name, package version, package name and whether client-side assets will be included.
3. Serve.json – Basically used for defining the start page and port when testing the solution using ‘gulp serve’
4. Write-manifests.json – In case you have a custom CDN defined for your SharePoint assets, you can defined the CDN path in this file. Custom CDN would be useful in case of a tenant used over multiple geographies. However, if the CDN path is not set, SharePoint would host the files on a default CDN from where they can be provisioned.
2. Node_modules folder – contains all the node modules that are installed for the solution. This is a bulky folder and usually not managed by the developer. All modules installed will be placed in the node_modules folder.
3. Src folder – This is the key folder where the web part/extension files will be placed. It would ideally contain
1. TypeScript file – Which would define the functionality of the WebPart/Extension. The TypeScript (.ts) file would contain a render function where you can define what your component will render.
2. JSON file – This is a manifest file which would be used to convert the TypeScript file to JavaScript file (as browser cannot understand TypeScript). Developers would not need to make any changes to this file.
3. SCSS file – This is a stylesheet file included to define the styles only for Web Parts. This file would not be present for extensions.
4. Temp folder – This folder contains the converted JS files (converted from TypeScript). This folder would be used to host and render the files when ‘gulp serve’ command is executed.
5. Gulpfile.js – This file contains the definition of all the gulp commands that we would execute for serving, bundling and packaging our solution
6. SharePoint folder – This folder is not present initially as part of the solution. Once, we execute ‘gulp package-solution’ command this folder is created. It contains the SharePoint Package (.sppkg) file that can be uploaded to the SharePoint App Catalog.

SharePoint SPFx Setup Without Administrative Rights

SPFx Setup

Requirements:

1. NodeJS package installed on your machine
2. Code editor such as Visual Studio Code

These are freeware and can be downloaded from the web and installed locally.

SPFx Setup for Windows (With Administrator Access):

To simplify the entire setup process (if you do have administrator access on your machine), it can be broken down into 3 simple steps:

1. Download NodeJS MSI installer and execute the installer as administrator
• You can download the NodeJS installer from: https://nodejs.org/en/
• After the download completes, execute the MSI file. Generally, this would install all the necessary files, register the node command in the global variables and download all required files in the Program Files/NodeJS folder.
2. Download and install Visual Studio Code
• You can download Visual Studio Code from: https://code.visualstudio.com/
• Run the exe file to install Visual Studio Code
  Please note: You can use any other code editor you are comfortable with – Atom, Webstorm etc.
3. Install the necessary tools for development – Yeoman, Gulp and SharePoint Generator, you would use the following commands from Command Prompt:
• Globally install Gulp and Yeoman –
  npm install -g yo gulp
• Globally install SharePoint Generator –
  npm install -g @microsoft/generator-sharepoint
• These commands would need to download files from the internet and install them locally, if you are behind a corporate proxy, you would need to set the proxy in the npm config files using the following commands:
  npm config set proxy [Your Proxy URL]
  npm config set https-proxy [Your Proxy URL]

SPFx Setup for Windows (Without Administrator Access on local machine):

In some cases, it would be possible that users do not have administrator access on their local machines, which would prevent them from running NodeJS installation. Below are the steps for setting up your development environment for SPFx, without administrative privileges:

1. Download the NodeJS zip folder for version 8.x and extract files locally
• You can download the NodeJS zip for version 8.x from: https://nodejs.org/dist/latest-v8.x/
• Copy the zip folder to a dedicated local location and extract all files. You will have a folder with the Node version as node-v8.x… This folder will contain the node.exe application
• Copy the path to the of the node.exe file and add it to the local environment variables of your machine.
  Please note: The local environment variables would allow you to execute the node.exe commands from any location of your machine, however, local environment variables work on a per user basis and would need to be installed for each user separately
2. Download and install Visual Studio Code
• You can download Visual Studio Code from: https://code.visualstudio.com/
• Run the exe file to install Visual Studio Code
  Please note: Visual Studio Code installation would not need Administrator privileges.
3. Install the necessary tools for development – Yeoman, Gulp and SharePoint Generator. Start Command Prompt and navigate to the folder where you would create your SPFx solution. You would use the following commands from Command Prompt:
• Install Gulp and Yeoman locally –
  npm install yo gulp
• Install SharePoint Generator locally –
  npm install @microsoft/generator-sharepoint
• These commands would need to download files from the internet and install them locally, if you are behind a corporate proxy, you would need to set the proxy in the npm config files using the following commands:
  npm config set proxy [Your Proxy URL]
  npm config set https-proxy [Your Proxy URL]
  Please note: The commands used here would add all the necessary node modules to the defined folder only. Referencing those modules outside the scope of that folder would not be possible

A significant portion of this blog is referred from: Set up your SharePoint Framework development environment

However, I have tried to rephrase and simplify the information to my best ability.