How to properly add an Application Customizer to an existing SPFx Web Part Project

Posted Tuesday, January 8, 2019 12:22 PM by CoreyRoth

The yo tools make it rather easy now to add additional web parts and extensions to your SPFx projects.  However, I recently ran across this issue which caused me weeks of pain.  The scenario starts with this. You create a new SPFx project with a web part and deploy it.  Everything works great.  Now, you go and create an application customizer to add your own navigation or footer.  Here is where you start to run into issues.  You can add the application customizer easily enough with yo, but when you increment your version number in package-solution.json and then deploy it, you will find your web part to be missing.  Your application customizer will work fine though.

All of this trouble comes from package-solution.json.  When you initially create an SPFx project with a web part, no features included in package-solution.json and the web part deployment just works.  However, when you add the application customizer, it creates a feature to deploy the application customizer.  Since there is no reference to the existing web part which means it no longer gets deployed.

{
   "$schema": "
https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
   "solution": {
     "name": "web-part-plus-app-customizer-client-side-solution",
     "id": "64380dc5-ce1e-4227-9b47-5ca7f9134d12",
     "version": "1.0.0.1",
     "includeClientSideAssets": true,
     "isDomainIsolated": false,
     "features": [
       {
         "title": "Application Extension - Deployment of custom action.",
         "description": "Deploys a custom action with ClientSideComponentId association",
         "id": "82cb0cda-24bf-4aec-87df-c9571f82ad6b",
         "version": "1.0.0.1",
         "assets": {
           "elementManifests": [
             "elements.xml",
             "clientsideinstance.xml"
           ]
         }
       }
     ]
   },
   "paths": {
     "zippedPackage": "solution/web-part-plus-app-customizer.sppkg"
   }
}

Your first inclination might be to add a feature for the web part.  Don't do that!  It will cause numerous issues for you in which SharePoint will load old versions of your code intermittently (see issue #3199).  Instead, you need to add a component id for each web part AND your application customizer into a single feature.  To be clear, you can only have a single feature in an SPFx project.  This is at least in the context of web parts and extensions.  I don't know how this would affect a feature that deploys declarative components such as site columns or content types. 

Here is what a package-solution.json looks like that will properly deploy a web part and an application customizer. 

{
   "$schema": "
https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
   "solution": {
     "name": "web-part-plus-app-customizer-client-side-solution",
     "id": "64380dc5-ce1e-4227-9b47-5ca7f9134d12",
     "version": "1.0.0.2",
     "includeClientSideAssets": true,
     "isDomainIsolated": false,
     "features": [
       {
         "title": "Application Extension - Deployment of custom action.",
         "description": "Deploys a custom action with ClientSideComponentId association",
         "id": "82cb0cda-24bf-4aec-87df-c9571f82ad6b",
         "version": "1.0.0.2",
         "assets": {
           "elementManifests": [
             "elements.xml",
             "clientsideinstance.xml"
           ]
         },
         "componentIds": [
           "2c3bc847-128a-4ed9-94b2-3f46b02e6924",
           "5bd48a40-6b4a-45b5-a919-95d12c9137a0"
         ]
       }
     ]
   },
   "paths": {
     "zippedPackage": "solution/web-part-plus-app-customizer.sppkg"
   }
}

Under componentIds you will see two ids.  The first is the id for the Application Customizer.  This isn't the feature id, it's the id in the manifest file for the application customizer.  The second component id is the id of the id of the web part (you also get that from the manifest).

When I was looking to originally add an application customizer to my web part project, I didn't find a lot of guidance on it.  You can reference my GitHub project with the issue.  The master branch has the issue, the WebPartWithApplicationCustomizer branch does not have the issue.  I've also logged an issue (#3219) for this scenario in GitHub because I think it could affect others as well.

Comments

No Comments

Leave a Comment

(required) 
(required) 
(optional)
(required)