Configuring serve.json for SharePoint Framework (SPFx) Local Workbench

As part of our SPFx development series, we’ll now dive into setting up the local environment to test web parts using the local workbench. The serve.json file plays a key role in this, allowing you to serve and test your web parts efficiently during development.

What is serve.json?

The serve.json file located in the config folder of your SPFx project defines how the development server behaves when you run the gulp serve command. It ensures that you can test your web part either on the local workbench or on a real SharePoint site.

1. Structure of the serve.json File

The basic structure of serve.json includes:

• HTTPS settings: Determines whether the project will be served over HTTPS.
• Initial page: Specifies where the workbench will be launched.
• Port configuration: Defines the port the development server listens on.
• Serve configurations: Allows customizations for different environments, such as local or SharePoint workbenches.

Here’s a sample configuration:

{
  "https": true,
  "initialPage": "https://localhost:4321/temp/workbench.html",
  "port": 4321,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://<your-sharepoint-site>/_layouts/15/workbench.aspx",
      "customActions": {
        "default": {
          "location": "ClientSideExtension.ApplicationCustomizer"
        }
      }
    }
  }
}

2. Configuring Local Workbench

In the example above, the initialPage key points to https://localhost:4321/temp/workbench.html, which launches the local workbench.

• Local Workbench: This is a sandbox environment where you can test your SPFx WebPart outside of a SharePoint site.
• To launch the local workbench, you just need to run:

gulp serve

This command opens the local development server at the specified port and displays your web part in the local workbench, allowing you to verify basic functionality without deploying to a SharePoint site.

3. Testing on SharePoint Workbench

If you need to test your web part on a real SharePoint site’s workbench, the pageUrl property should be configured to point to the workbench of your SharePoint site.

Here’s how to adjust the configuration:

"serveConfigurations": {
  "default": {
    "pageUrl": "https://your-sharepoint-site/_layouts/15/workbench.aspx"
  }
}

Once the pageUrl is set, running gulp serve will now open your web part in the SharePoint site’s online workbench, allowing you to test against real data and services.

4. Securing the Development Environment

Since modern browsers enforce HTTPS for SharePoint Framework development, it’s critical to enable HTTPS in your serve.json configuration:

"https": true

By default, the SPFx environment is set up with self-signed certificates, but you can install trusted certificates for smoother development if your organization requires it.

5. Custom Actions (Optional)

The customActions section in serve.json is optional and useful when you need to test Application Customizers (such as header/footer customizations) or extensions. It allows you to specify where the customizations will be injected, helping you preview your changes in the right context.

Here’s a simple configuration example:

"customActions": {
  "default": {
    "location": "ClientSideExtension.ApplicationCustomizer",
    "properties": {
      "exampleProp": "exampleValue"
    }
  }
}

This can be particularly useful when developing SPFx extensions that affect the UI of SharePoint pages.

6. Running the Development Server

Once your serve.json file is properly configured, simply run:

gulp serve

This launches the local development server. Based on the configurations in serve.json, the development server either launches the local workbench or the online workbench on a real SharePoint site.

Conclusion

Configuring the serve.json file is an essential part of SPFx development, allowing you to easily test and serve your web parts in both local and SharePoint environments. By understanding the various sections of the serve.json file—such as HTTPS setup, initial pages, and custom actions—you can streamline your development process, ensuring your web parts are tested efficiently before deployment.

Key Points to Remember:

• Local Workbench is useful for quick, offline testing.
• Online Workbench enables testing with real SharePoint data.
• Use HTTPS to comply with modern browser security requirements.
• Customize the development environment using customActions for specific extension testing.

Related Resources

• Microsoft Documentation on SharePoint Framework
• Developing with SPFx

This setup will ensure that your SPFx development experience is smooth and efficient, whether you’re working locally or directly in SharePoint.

Summary of Commands Used in SPFx Development for Workbench:

1. Start Development Server:

   gulp serve

• Serves your SPFx web part in the local or SharePoint workbench.

1. Configure serve.json:

• Set up the HTTPS, port, and URL for testing:

   {
     "https": true,
     "initialPage": "https://localhost:4321/temp/workbench.html",
     "port": 4321
   }

3. Modify for SharePoint Workbench:

   {
     "pageUrl": "https://your-sharepoint-site/_layouts/15/workbench.aspx"
   }

4. Run SharePoint Extensions (Optional):

   "customActions": { "location": "ClientSideExtension.ApplicationCustomizer" }

This summary provides the essential commands for testing and serving SPFx web parts efficiently.