Avoid errors editing SharePoint Framework project configuration with Visual Studio Code intellisense


SharePoint Framework uses JSON files to store project configuration. Here is how you can edit these files easily in Visual Studio Code.

SharePoint Framework project configuration as JSON

SharePoint Framework is a new model for building SharePoint customizations. It has been made from the ground up focusing on web stack development using cross-platform open source tools such as Node.js, Gulp or webpack to name a few.

In the past building SharePoint solutions was done primarily on Windows using Visual Studio. Back then, SharePoint projects were built using a specific Visual Studio project template. All project settings were stored in the .csproj project file using an XML structure.

Developing on the web stack, JSON is a more commonly used format for storing configuration data. If you look at a SharePoint Framework project, in the config folder you will find a number of files defining the configuration of your project: from the web parts included in the project, to how the different build tasks should be run.

The config folder in a SharePoint Framework project highlighted in the explorer pane of Visual Studio Code

While JSON is easier to work with than XML, originally it had one important flaw: there was no way to define the data structure that should be used. As a result, entering data in JSON was error-prone and validating the correctness of the structure was a tedious task. Where in XML you could refer to an XSD to verify the correctness of your data structure, there was nothing alike in JSON. To solve this problem, JSON schema was introduced. While there are different opinions about it, one thing is sure: it makes your life easier when working with SharePoint Framework projects.

Editing SharePoint Framework config files

When building solutions on the SharePoint Framework, you regularly need to change something in one of the config files: whether to specify where your solution should be deployed to or to reference an external script. By default, you are on your own doing this.

Adding a reference to an external script in SharePoint Framework project configuration
Will this work?

Basically you need to use a trial & error approach to see if the applied changes are correct and are being picked up by the SharePoint Framework toolchain.

Build error caused by incorrectly referencing Angular as an external script in the SharePoint Framework

There is however a better way to easily edit SharePoint Framework project configuration files.

Easily edit SharePoint Framework config files in Visual Studio Code

The SharePoint Framework team did a great job of providing JSON schema files for the project configuration files. These files are included in the different packages where the code processing the corresponding config file is located. While you could use these schema files to manually verify that your configuration is correct, did you know that you can have Visual Studio Code do that automatically for you?

Visual Studio Code supports associating JSON schemas with specific files. Using this capability, you can associate schema with each configuration file and get intellisense when editing SharePoint Framework project configuration!

You can define JSON schema for specific files in Visual Studio Code either globally or in the project workspace. If you’re working with SharePoint Framework projects regularly, it would make sense to have it defined globally. In Visual Studio Code, open Settings, and in the settings.json file, add the following json.schemas section:

{
  "json.schemas": [
    {
      "fileMatch": [
        "/config/config.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-web/lib/schemas/config.schema.json"
    },
    {
      "fileMatch": [
        "/config/copy-assets.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/copyAssets/copy-assets.schema.json"
    },
    {
      "fileMatch": [
        "/config/deploy-azure-storage.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/deployAzureStorage/deploy-azure-storage.schema.json"
    },
    {
      "fileMatch": [
        "/config/package-solution.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/packageSolution/package-solution.schema.json"
    },
    {
      "fileMatch": [
        "/config/serve.json"
      ],
      "url": "./node_modules/@microsoft/gulp-core-build-serve/lib/serve.schema.json"
    },
    {
      "fileMatch": [
        "/config/tslint.json"
      ],
      "url": "./node_modules/@microsoft/gulp-core-build-typescript/lib/schemas/tslint.schema.json"
    },
    {
      "fileMatch": [
        "/config/write-manifests.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/writeManifests/write-manifests.schema.json"
    },
    {
      "fileMatch": [
        "/config/configure-webpack.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/configureWebpack/configure-webpack.schema.json"
    },
    {
      "fileMatch": [
        "/config/configure-external-bundling-webpack.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/configureWebpack/configure-webpack-external-bundling.schema.json"
    },
    {
      "fileMatch": [
        "/copy-static-assets.json"
      ],
      "url": "./node_modules/@microsoft/sp-build-core-tasks/lib/copyStaticAssets/copy-static-assets.schema.json"
    }
  ]
}

Grab the snippet at https://gist.github.com/waldekmastykarz/1c95bc4f637ce7d5ff71e4882ee32efa

When you save the Visual Studio Code configuration, the next time you open one of the SharePoint Framework project configuration files, you will get intellisense and instant feedback of anything that’s not correct.

Visual Studio Code pointing out an invalid property in a SharePoint Framework project configuration file

Visual Studio Code providing intelligence when editing SharePoint Framework project configuration

Summary

SharePoint Framework uses JSON files to store project configuration. Editing these files manually is error-prone. In Visual Studio Code you can associate the JSON schema files provided with the SharePoint Framework, with the different configuration files and get intellisense and instant feedback when editing your SharePoint Framework project configuration.

Others found also helpful: