The Complete Guide to Setting Up SharePoint SPFx Development for SharePoint Subscription Edition

2.Install the SPFx Toolchain

Next, install Yeoman, Gulp CLI and the SharePoint generator:

npm install -g yo gulp-cli

npm install -g @microsoft/generator-sharepoint@1.15.2

Verify that the correct generator is active:

npm list -g @microsoft/generator-sharepoint

You should see:

@microsoft/generator-sharepoint@1.15.2

Treat this verification as part of the setup rather than an optional check. If developers maintain several SharePoint framework SPFx development environments, globally installed packages can easily point to an unexpected version.

Some dependencies in this SPFx generation may also require legacy native build tooling. If npm install fails with node-gyp, Python or C++ compilation errors, investigate the build dependency reported by the error rather than repeatedly reinstalling the SPFx generator.

3.Generate the First SPFx Project

Create a dedicated workspace:

mkdir SPFx-Projects

cd SPFx-Projects

Then launch the generator:

yo @microsoft/sharepoint

Create a simple Web Part project. For example:

Solution name: HelloWorldWebPart

Component type: WebPart

Web part name: HelloWorld

Framework: No framework

Let npm complete dependency installation before opening or modifying the project. Deprecation warnings can appear because SPFx 1.15.2 relies on packages from an older JavaScript toolchain. A warning does not automatically mean that the installation has failed.

With a SharePoint development SPFx setup, focus on distinguishing harmless warnings from genuine build errors.. Always work from the final npm or Gulp result.

4.Configure the SharePoint Workbench

Open:

config/serve.json

Configure the SharePoint-hosted workbench as the initial page:

{

“$schema”: “https://developer.microsoft.com/json-schemas/SPFx-build/SPFx-serve.schema.json”,

“port”: 4321,

“https”: true,

“initialPage”: “https://your-sharepoint-server/_layouts/15/workbench.aspx”

}

Replace your-sharepoint-server with the actual SharePoint URL.

Then trust the local development certificate:

gulp trust-dev-cert

Start the development server:

gulp serve –nobrowser

A successful SharePoint SPFx development session should start the HTTPS development server on port 4321.

Make sure you keep that terminal running while testing the component.

5.Verify the SharePoint Server Configuration

The workstation is only half of the environment. You must also configure SharePoint to support the SPFx deployment workflow.

Check that the farm has the required service applications and an App Catalog. You can inspect the Subscription Settings service configuration through SharePoint PowerShell:

Get-SPServiceApplication |

Where-Object {$_.TypeName -like “*Subscription*”}

Get-SPServiceApplicationProxy |

Where-Object {$_.TypeName -like “*Subscription*”}

You can also inspect the relevant service instance:

Get-SPServiceInstance |

Where-Object {$_.TypeName -like “*Subscription Settings*”} |

Select TypeName, Status

Verify the farm configuration before creating or changing service applications. Server-side changes should follow your organisation’s SharePoint topology, database naming, service account and change-management standards.

The App Catalog is equally important when moving from development into packaged deployment. Production builds typically use:

gulp bundle –ship

gulp package-solution –ship

These commands generate the optimised assets and .sppkg package used by the SharePoint deployment process.

Troubleshooting SharePoint SPFx development

Most setup failures fall into a small number of categories.

a) Primordials is not defined

Start by checking:

node –version

An incompatible Node.js runtime is a common cause. For the environment described here, confirm that Node.js 16.20.2 and SPFx 1.15.2 are active.

b) Port 4321 is already in use

Find the process:

netstat -ano | findstr :4321

Then terminate the appropriate process if it is safe to do so:

taskkill /PID <PID> /F

c) The project builds locally, but the web part fails in SharePoint

This usually means you should stop debugging TypeScript and inspect the SharePoint side. Check the browser console, service applications, SharePoint-hosted workbench, App Catalog configuration and component manifest loading.

Errors such as:

[SPLoaderError.loadComponentError]

Failed to load component

indicate that the client could not resolve or load the component correctly. Separating local build problems from farm configuration problems is one of the most useful habits in SharePoint development SPFx troubleshooting.

A Missing Piece Nobody Warns You About

If your web part runs fine on the local workbench but disappears or throws a manifest not found error on the actual SharePoint workbench, you’re almost certainly missing the Subscription Settings Service Application. This is a genuinely new requirement in Subscription Edition – it doesn’t exist in SharePoint 2019 at all, which is exactly why so many teams migrating from older environments get stuck here without understanding why.

On the server, run PowerShell as Administrator and create the service application along with its proxy, using New-SPSubscriptionSettingsServiceApplication and its matching proxy cmdlet. Start the resulting service instance and confirm its status reads Online before testing again. Once this service is live, manifests register correctly and your web parts load exactly as they should. It’s a five-minute fix once you know it’s the culprit – the frustrating part is getting to that realisation in the first place.