Deep Dive Into SharePoint Framework (SPFx) Webpart Configuration

SharePoint is one of the most powerful collaboration tools which has been around for decades and is evolving day by day. Another jewel in its crown is SharePoint Framework is both a page and webpart model which provides full support for client-side development.

In this article we are not going to see how to develop it, we are going one step forward and discussing its configuration options available. If you want to learn about building SharePoint Framework webparts and extensions, please follow the below links,

How to change SPFx bundle file name?

Whenever you run gulp bundle –ship command, a new bundle file will be created with some prefix and it appends with GUID at the end. GUID is auto generated to maintain the uniqueness of a file, but you can change the prefix of that bundle file.

Go to config folder in your project and look for config.json, the highlighted content in the below snippet is your bundled file’s prefix. You can change it as per your wish with a meaningful name.

{
"$schema": "https://dev.office.com/json-schemas/spfx-build/config.2.0.schema.json",
"version": "2.0",
"bundles": {
"first-sp-fx-web-part": {
"components": [
{
"entrypoint": "./lib/webparts/firstSpFx1/FirstSpFxWebPart.js",
"manifest": "./src/webparts/firstSpFx1/FirstSpFxWebPart.manifest.json"
}
]
}
},
"externals": {},
"localizedResources": {
"FirstSpFxWebPartStrings": "lib/webparts/firstSpFx1/loc/{locale}.js"
}
}

What happens if I change the webpart folder name in SPFx?

If you change the webpart folder name alone without changing the appropriate configurations, you will end up with the error like below, “No localized files found under the root directory”

So, whenever you change the webpart folder name make sure to change the below localized resources path in config.json

{
"$schema": "https://dev.office.com/json-schemas/spfx-build/config.2.0.schema.json",
"version": "2.0",
"bundles": {
"first-sp-fx-web-part": {
"components": [
{
"entrypoint": "./lib/webparts/firstSpFx1/FirstSpFxWebPart.js",
"manifest": "./src/webparts/firstSpFx1/FirstSpFxWebPart.manifest.json"
}
]
}
},
"externals": {},
"localizedResources": {
"FirstSpFxWebPartStrings": "lib/webparts/firstSpFx1/loc/{locale}.js"
}
}

How to change the solution name in SPFx?

How to change SPFx app version?

How to publish SPFx app assests to Office 365 CDN?

How to change the package (.sppkg) file name in SPFx?

The answer for all these questions resides in same file in the location config/package-solution.json

{
"$schema": "https://dev.office.com/json-schemas/spfx-build/package-solution.schema.json",
"solution": {
"name": "spfx-1-client-side-solution",
"id": "4b4c2d39-b01c-48c9-894d-22781dda4fb6",
"version": "0.0.0.3",
"includeClientSideAssets": true,
"skipFeatureDeployment": true
},
"paths": {
"zippedPackage": "solution/spfx-1.sppkg"
}
}

In the above snippet I have highlighted answers for the above questions, where you could change the version/solution name/publish in office 365 CDN/package name.

Please refer to this blog to host webpart in office 365 CDN.

How to hide SPFx webpart from toolbox?

Even after deploying the SPFx webparts globally we have got an option to hide it from normal users to directly add the webpart in the page. To enable this setting, please go to the WebPart.manifest.json file in file location,

/src/webparts/{webpartname}/{WebPartName}WebPart.manifest.json

A property called “hiddenFromToolbox” is used to hide the webparts in toolbox, which will look like below,

{
"$schema": "https://dev.office.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
"id": "045784e8-5861-4078-b2eb-a74288f15c3e",
"alias": "FirstSpFxWebPart",
"componentType": "WebPart",
// The "*" signifies that the version should be taken from the package.json
"version": "*",
"manifestVersion": 2,
// If true, the component can only be installed on sites where Custom Script is allowed.
// Components that allow authors to embed arbitrary script code should set this to true.
// https://support.office.com/en-us/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
"requiresCustomScript": false,
"hiddenFromToolbox": true,
"preconfiguredEntries": [{
"groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
"group": { "default": "Other" },
"title": { "default": "First-SPFx" },
"description": { "default": "First-SPFx description" },
"officeFabricIconFontName": "Page",
"properties": {
"description": "First-SPFx Properties"
}
}]
}

How to place all the SPFx webparts to be appeared in same toolbox folder?

How to change the SPFx webpart title?

Answers for these questions reside in the webpart manifest file which is in the below location to do the settings for that

/src/webparts/{webpartname}/{WebPartName}WebPart.manifest.json

"preconfiguredEntries": [{
"groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
"group": { "default": "Other" },
"title": { "default": "First-SPFx" },
"description": { "default": "First-SPFx description" },
"officeFabricIconFontName": "Page",
"properties": {
"description": "First-SPFx Properties"
}
}]

If you maintain the same group id and same group name in all your apps, you will be able to see all SPFx webapps under one folder.

Where to mention the external CDN path in SPFx?

If you have decided to host the SPFx app external CDN other than Office 365 public CDN, where to specify the base CDN path in SPFx? There is a setting for this in the config/write-manifests.json file which is highlighted below,

{
"$schema": "https://dev.office.com/json-schemas/spfx-build/write-manifests.schema.json",
"cdnBasePath": "https://azureCDNUrl/container/Spfx"
}

Note: If you specify the external CDN path in the above image then includeClientSideAssets property setting in config/package-solution.json will be ignored and assets won’t be deployed in Office 365 CDN along with .sppkg file. A warning will be displayed in command prompt for the same as below,

What will happen if I run gulp clean in SPFx?

This is a predefined task in SPFx package which cleans up all the files/folders that are created temporarily at runtime. For example, it will delete the folders like lib, temp, dist,. Don’t worry these folders will be created again when you build/bundle the SPFx apps.

Where to specify the azure storage container details in SPFx?

If you want to host your SPFx apps in Azure CDN storage container, SPFx provides options for that as well in the config/deploy-azure-storage.json file. Use the gulp task gulp deploy-azure-storage

{
"$schema": "https://dev.office.com/json-schemas/spfx-build/deploy-azure-storage.schema.json",
"workingDir": "./temp/deploy/",
"account": "",
"container": "spfx-1",
"accessKey": ""
}

workingDir - all files from this location will be moved to Azure
account - Azure storage account name
container - storage container name of this app
accessKey - Key to access the storage account

Please follow this blog to know more about CDN.

In this article we have discussed some of the configuration setup and its usage with some screen shots in SPFx. Still there are some more to go and new set of configurations are expected to come in the upcoming SPFx releases which you can find in my next article.

If you have any questions/issues about this article, please let me know in the comments.