Extract and customize a single web part from the SharePoint Starter Kit
Few months ago a starter kit for modern SharePoint development has been released. The whole kit is a sort of intranet portal demo which covers all the capabilities given by the SharePoint Framework (SPFx). Beside the demo aspect of it, it comes also as a great help for developers (and not really developers like me) to get started with building solutions for modern SharePoint Online.
The starter kit is made of several web parts and extensions (see the official repo), however when deploying in production we might not want to publish all these web parts and extensions as such (if you want to test the whole thing, do that in a dev tenant).
Get the sp-starter-kit
First clone the repo on your machine or just download the whole package as a zip.
Note that at this point in time, I’m using the dev branch as there is some issue to deploy the current branch package (should be fixed soon or already if you are from the future).
When you unzip the package, you will see multiple folders. The web parts and extensions are under the solution folder.
And under solution you will find the “standard” folders and files when you create a SPFx solution.
Create a SPFx web part
For this example I want to extract the World Time web part (quiet simple one, no interaction with APIs).
We will create a new SPFx solution and name it WorldClock so it has a different name as the original web part (if the starter kit web part has already been deployed).
Before that, you have to get all the tooling ready on your machine for SharePoint Framework development if it’s not already the case. See the official doc to prep your dev environment.
So open your terminal and in the path where you want to store this project, type the commands as below.
md worldclockcd worldclockyo @microsoft/sharepoint
For the options, you can set as below, but basically everything as standard except for choosing React as framework as it’s needed for the web part we are copying (seems like all web parts from the starter kit are based on React).
You will end up with the basic folders and files for a SPFx web part.
Import the starter kit web part
Now we can just delete all the folders and files under src/webparts/worldClock and copy over the content from the original worldTime web part.
And then we have to rename the files to match our web part name.
In Visual Studio Code (or your prefer editor), check all files to replace WorldTimeWebPart by WorldClockWebPart.
Also change the web part title in the .manifest.json file.
You can change the default properties for description and time zone offset here too.
Now you can start the local workbench to test the web part.
gulp serve
At this point if you have no error, you should see the workbench starting in your default browser.
Add the web part, and it should work with the properties defined.
If you don’t want to do further changes, you can already prepare and package your solution. I suppose that you want to host the web parts assets from SharePoint app catalog directly or from the Office 365 CDN (see the official doc for more info). In that case all assets will be included in the solution package.
Run from your web part path the 2 following commands.
gulp bundle --shipgulp package-solution --ship
The package can be found in the sharepoint/solution.
Now you can just drag and drop this .sppkg file to your SharePoint app catalog (but maybe keep reading first…).
However at this point I ran into one issue, as the component unique ID was also used in the starter kit already installed in this tenant.
The ID of the webpart can be found in the .manifest.json file.
If you want a new unique ID you can use the snippet below in PowerShell.
[guid]::NewGuid() | Select-Object -ExpandProperty Guid | clip
And paste the value in place of the existing one. Then repackage the solution.
But again when I did that, I was still getting the same error “Component ID {0} exists in solution {1} already” (not sure why {0} and {1} are not replaced by the respective values).
So I opened the .sppkg file with 7-zip to find out that I had created a mess.
In the dist folder I can see the duplicate manifests with the different IDs.
So if you already bundled the solution before changing the ID, it’s necessary to go through some clean-up. You can just delete all content from the following folders.
dist
sharepoint/solution
temp
Then you can re-run gulp to build and package the solution.
This time the package should only include stuff with the last defined unique ID in the manifest.json.
And when you upload the package to the app catalog, you should get no error.
In this example, I didn’t set the solution to be available on all sites, so it has to be manually added to the site (Site contents > New > App > select the web part).
After a while the web part will be available, and we can add it on a page.
Set the deployment scope
If you want the web part to be available on all sites without adding the app manually on each site, you can add the following property to package-solution.json.
"skipFeatureDeployment": true
When this option is added, we have to confirm to make the SharePoint solution available on sites at deployment in the app catalog.
Sum up
In the end this method to extract a single web part from the modern SharePoint Starter Kit is working, but I feel like it’s too “hacky” and there is probably a proper way to do it. And remember that this is useful if you want to only re-use one or few web parts of the SharePoint Starter Kit, and also that you plan to do further customization (enhancement, branding etc…).
Also in this example it was not the case, but some web parts will require more dependencies. For example some web parts are using “@pnp/spfx-controls-react”, if it’s missing your should see errors in the VS Code, and when you will try to serve or bundle the solution. You must add the dependencies in package.json at the root of your solution folder.
And then have it added to the SharePoint solution with the following command at the root of your solution folder.
npm install
Steps summary
- Download the whole solution from GitHub (could be another solution from sp-dev-fx-webparts)
- Create a new solution locally (with appropriate framework)
- Delete the generated files in the src/webparts folder
- Copy over the content from src/webparts of the original sample solution
- Rename the file to match your solution name
- Replace all references in all the files with the new file names
- Change the unique ID in manifest.json
- Add missing dependencies in package.json and run npm install
- Make other changes and customization as needed
- Test the solution with gulp server
- Package the solution and deploy to your app catalog
- Enjoy your new web part on any SharePoint page
Please leave a comment if you can advise on a better way to achieve this, or if you have any question.