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:- Gulp bundle
- 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:
- 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.
- 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.
- App Catalog at Site Collection Level – You can provision an App Catalog for your Site Collection by running the following commands:
- 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’. - 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’.
- 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.
- Re-package the Solution – You would need to change the version number and rerun the packaging commands to re-package the solution.
- Open the ‘package-solution.json’ file in the ‘config’ folder.
- Update the version number for the solution parameter and save the file.
- 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. - 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. - Upgrade the Installed SPFx Solution – For upgrading the solution:
- Browse to the Site Contents page of the site.
- 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.
- In the classic SharePoint UI click on the ellipsis beside your app and click 'About'.
- 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.
