Recently a new serveConfigurations section was added to the serve.json config file in new SPFx Extension projects. These are a huge help when it comes to debugging extensions and are especially helpful when testing ClientSideProperties.
Prior to the introduction of serveConfigurations, you couldn’t just run the gulp serve command like you do for webparts since that launches the local workbench where extensions couldn’t (and still can’t) be tested.
So the advice was to use gulp serve –nobrowser and then just navigate manually to a page in O365 and paste an ugly (and easy to screw up) set of querystrings.
Waldek Mastykarz even created a gulp task, gulp serve-info, that made this a little easier. I used it in my extensions and it was a huge leg up, but the whole thing was still clunky and a significant complexity preventing new developers from getting into extension development (or at least frustrating them).
What was needed was something as simple as gulp serve that took into account your custom locations and unique property settings. Fortunately, that’s where serveConfigurations comes in!
Setting up your serveConfigurations
When you generate a new SPFx Extension you’ll find a couple of initial serveConfiguration entries were created for you automatically in the config/serve.json file:
The values of these configurations should remind you of all of those querystring parameters because that’s exactly how these are going to be used. These values will build the URL for you when you serve your solution. The IDs and properties all match what was generated (although you are unlikely to keep the testMessage property for long).
The first thing you should do is replace the pageUrl property with the page address in your O365 tenant where you want to test the extension. Keep in mind these values are NOT used in the final package and are only for testing.
The sample above is for an Application Customizer (which is why the location property exists). Each type of extension will have slightly different properties (same as the debug querystrings), but will be added for you with your extension.
If you’re only doing a single extension in your solution and you aren’t using ClientSideProperties then all you need is the default entry using your own pageUrl value. If however, you have multiple extensions, then you’ll want an entry for each so that you can selectively decide which one you are serving when running gulp serve.
It is also comes in handy when you want to test different ClientSideProperty configurations. For my Field Customizer sample SPFx Item Order I allowed users to specify an OrderField property. When it was present the extension did one thing and when it wasn’t it did another.
To make this easy I included 2 serveConfigurations entries (one with the property and one without):
Using the serveConfigurations
Text in a json file! WOW! But how does this help?
Now when you run gulp serve the default serveConfiguration entry will be used and the browser will go to the pageUrl you specified and the debug querystring will be built using the values you provided!
Even better, you can specify which serveConfiguration you want to use using the –config parameter. So for the Item Order Field Customizer shown above, I could test the custom field configuration by entering this at a command prompt:
gulp serve --config=customField
Now the browser will be launched and my custom property will be set!
You can even see the URL that the browser will be sent to directly in the command output:
Aren’t you glad you didn’t have to type that (and get it right)? So, if you’re doing SPFx Extension development, serveConfigurations makes your life much easier!
3 thoughts on “Utilizing SPFx serveConfigurations”
[…] Chris Kent has a blog post discussing this. https://thechriskent.com/2017/11/03/utilizing-spfx-serveconfigurations/ […]
Is have an SFPX application customizer and the “serverConfigurations” element of my serve.json file is not allowed and shows a squiggly under it.
I have no idea how to correct this.
This is an issue with the schema validation (incorrectly adding the squiggly). This is caused by the teams not really understanding JSON schema files. The value will work, however. Unfortunately, this isn’t the only false squiggly you’ll see in these config files.