HowTo: Create, build & run development and production versions of an SPFx application

Brent Ely
Brent Ely
Oct 30 · 3 min read
Photo by Fletcher Pride on Unsplash

Modern SharePoint apps written using the SharePoint Framework (SPFx) create an .sppkg file for your Site Collection App Catalog. That’s it — a single production version.

What’s the process for creating multiple (dev or QA) versions of your app?

Traditionally, we all have some sort of dev/test page for QA, UAT, etc. before we push an app to production. When I used to create Content Editor Webpart (CEWP) solutions, i would upload my app.jsfile to SiteAssets, then create a page to hold it (e.g.: “./SitePages/app.aspx”), then do the same for a dev/qa version.

The benefit of the CEWP-based approach is that it allows for having a test page as we could take the same application code, either as head branch code or a WIP page, and create a page to test that code until it is approved for production.

The option does not exist when creating SPFx applications. Additionally, simply renaming the build output from “app.sppkg” to “app-dev.sppkg” and uploading to the AppCatalog will not work. (It’ll either clobber the existing app or be disabled and unavailable in modern page Web Part pickers).

Lastly, while the built-in workbench is super helpful (it builds every time we save!) it cannot be used for UAT, demoing features to your boss, etc. There has to be a way to create multiple versions using our modern SPFx tooling…

It turns out that there is a way to create multiple builds of an SPFx app. A post on StackExchange mentions that the SPFx master himself, Vesa Juvonen, discussed this topic on a SharePoint community call and the guidance was:

change the solution id and solution name to make it a distict (sic) package. Also change the paths Zipped-Package

Not exactly a detailed guide — the other answers provided no further detail either.

Photo by Olav Ahrens Røtne on Unsplash

Here is how to build a development version of an SPFx solution.

Update 1: config/package-solution.json

"$schema": "https://[...]/package-solution.schema.json",
"solution": {
//"name": "db-search-client-side-solution",
"name": "db-search-client-side-solution-dev",
//"id": "1fd3a2ed-7246-4d13-8d2a-489c4d2bf06c",
"id": "1fd3a2ed-7246-4d13-8d2a-489c4d2bf06d",
"version": "",
"includeClientSideAssets": true,
"isDomainIsolated": false
"paths": {
//"zippedPackage": "solution/db-search.sppkg"
"zippedPackage": "solution/db-search-dev.sppkg"

Summary: Append “-dev” to both the name and zippedPackage strings and modify the id value.

Update 2: src/webparts/<projectname>/*WebPart.manifest.json

"$schema": "https://[...]-web-part-manifest.schema.json",
//"id": "87ab2c67-4d3d-4785-8f79-24fdaa610525",
"id": "87ab2c67-4d3d-4785-8f79-24fdaa610526",
"preconfiguredEntries": [{
//"description": { "default": "Database Search" },
"description": { "default": "Database Search (Dev)" },

Summary: Alter the id value and modify the description field (otherwise, your web part picker will have two apps with the same name and you won’t be able to distinguish which is the dev version).

Run a build and when you look in sharepoint/solution you’ll see two files, each being a distinct app in the AppCatalog. Upload the dev one to your catalog, add it as an app on your site, and it’ll be available for selection on a page in the web part picker .

Now you can create “SearchDev.aspx” alongside “Search.aspx” with the newest builds and resume a normal SDLC.

Happy coding!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade