Which Deployment Scope?
Before we can deploy our SharePoint Framework webpart, the first thing we need to do is decide which deployment scope we will use. There are two options available: Tenant Scope or Site Collection Scope.
The SharePoint Framework leverages much of the existing Add-in Model infrastructure including the App Catalog. Traditionally, the App Catalog has always been scoped at the tenant or farm. Recently, Microsoft announced the Site Collection App Catalog which offers greater flexibility, especially for QA or test environment scenarios.
Allows deployment of SharePoint Framework packages across a SharePoint Online tenant or SharePoint 2016 On-prem farm. You have the choice to make your webpart available to all site collections immediately or instead require a site owner to add the webpart “app” to their site to make the webpart available on pages.
Site Collection Scope
Allows deployment of SharePoint Framework packages to a single SharePoint site collection. Like tenant scope, you have the choice between making your webpart available to all subsites within the site collection immediate or require a subsite owner to add the webpart “app” to their subsite. Please note that Site Collection scoped deployment is only available in SharePoint Online.
Set Up the App Catalog
Now that we have chosen a deployment scope, the next thing we need to do is ensure we have an App Catalog setup for us to deploy to. The App Catalog is the container in which we will upload our SharePoint Framework packages so that sites in that scope may use them. The steps to setup the App Catalog are generally simpler in SharePoint Online than SharePoint 2016 On-prem, though the deployment of SharePoint Framework packages is supported in both.
SharePoint Online: Setup Tenant App Catalog
SharePoint Online: Setup Site Collection App Catalog
SharePoint 2016 On-prem: SPFx Support and Considerations
SharePoint 2016 On-prem: Setup Tenant App Catalog
To deploy our webpart, we first need to create a deployable package that can be added to the App Catalog. You may follow the steps below to create your SPFx webpart package.
- Launch a console window, then change to the directory where your SPFx webpart project lives.
- Build your SPFx webpart project source code using the gulp bundle task.
Note: To minify your source code, append –ship to your gulp command.
- Create your SPFx webpart package using the gulp package-solution task.
Note: To include all client-side assets in your package that should be hosted by the CDN, append –ship to your gulp command. Read more about the Office 365 Content Delivery Network (CDN).
- Upload your SPFx webpart package to the SharePoint App Catalog. The package “.sppkg” file is created when you run gulp package-solution and it is saved into the directory: \myproject\sharepoint\solution\myproject.sppkg. You can simply open the directory in Windows Explorer and then drag-and-drop the “.sppkg” file into your App Catalog.
- Once your SPFx webpart package has finished uploading, you will be prompted with a dialog window to complete the deployment. This is where you will choose whether to deploy to all sites within your tenant or to all subsites within your site collection. Make your selection and then click the Deploy button.
- You’ve deployed your SPFx webpart! Now, let’s add the new webpart to a modern page.
Note: If you did not select “Make this solution available to all sites in the organization”, you would first have to add your SPFx app to your site before you will be able to add it to a page.
Hint: What if I don’t see the “Make this solution available to all sites in the organization” checkbox?
When you originally created your SPFx project using the SharePoint Yeoman generator, there was a question which asked if you would like to allow the tenant admin the ability to deploy the solution to all sites. Answering yes to this question sets the skipFeatureDeployment property to true in the package-solution.json file which ultimately indicates whether or not the “Make this solution available to all sites in the organization” checkbox is shown. To enable or disable this functionality after the project is generated, you may update the skipFeatureDeployment property within your package-solution.json file and then re-bundle and re-deploy.