Automating SharePoint Framework Solution Versioning with Gulp and NPM

If you’re like me and want to automate the versioning of a SharePoint Framework solution you’re in the right place!

I use this in most of my SPFx projects to keep synchronized the property version of the package.json and package-solution.json files.

If you’re interested in the code you can find a sample web part solution here.

To enable the synchronization automation first add the following code to the gulpfile.js:

gulp.task("sync-version",
 gulp.series(function (resolve) {
 // import gulp utilits to write error messages
 const gutil = require("gulp-util");

 // import file system utilities form nodeJS
 const fs = require("fs");

 // read package.json
 var pkgConfig = require("./package.json");

 // read configuration of web part solution file
 var pkgSolution = require("./config/package-solution.json");

 // log old version
 gutil.log("Old Version:\t" + pkgSolution.solution.version);

 // Generate new MS compliant version number
 var newVersionNumber = pkgConfig.version.split("-")[0] + ".0";

 // assign newly generated version number to web part version
 pkgSolution.solution.version = newVersionNumber;

 // Update every feature version
 for (var i = 0; i < pkgSolution.solution.features.length; i++) {
  let f = pkgSolution.solution.features[i];
  f.version = newVersionNumber;
 }

 // log new version
 gutil.log("New Version:\t" + pkgSolution.solution.version);

 var pkgSolutionString = JSON.stringify(pkgSolution, null, 4);

 if (pkgSolutionString && pkgSolutionString.length > 0) {
  // write changed package-solution file
  fs.writeFile("./config/package-solution.json",
                pkgSolutionString,
                (err) => {}
  );
 }

 resolve();
}));

The code adds a custom sync-version command that execute the following steps:

• read the package.json file
• read the package-solution.json file
• parse the version of the package.json file and set it to the package-solution.json file.

At this time the question would be: Ok, but how do it increase the version?

The answer is simple, the version increase is handled by the following NPM command:

npm version patch

The command increase the patch part of the version string, there are other supported parameters that you can check on the official documentation.

For a quick reference about how is the version string composed you can have a look at the NPM semantic versioning documentation here.

Proceding with the setup the next thing would be to add a custom script in the package.json file where, beside the build/clean/bundle and package-solution commands, there are also the NPM increase version and the custom gulp command to synchronize the version:

"scripts": {
  ...omitted for brevity...
  "package": "gulp build && npm version patch && gulp sync-version && gulp clean && gulp bundle && gulp package-solution"
},

Finally, to execute all the previous commands you can simply run the following:

npm run package

This will perform all the following operations just by running a simple command:

• gulp build
• npm version patch: the NPM script to increment the version patch.
• gulp sync-version: the custom GULP command to synchronize the version from the package.json file to the package-solution.json file.
• gulp clean
• gulp bundle
• gulp package-solution

In the end an SPPKG file of the solution will be created with the updated version.

For a production package you can enhance the commands using the --ship flag:

"scripts": {
  ...omitted for brevity...
  "package:prod": "gulp build && npm version patch && gulp sync-version && gulp clean && gulp bundle --ship && gulp package-solution --ship"
},

The NPM command to execute the production package will be:

npm run package:prod

I sincerely hope that this article helped you with your SharePoint Framework solution versioning and if you have any improvements or suggestions please let me know.

Hope this helps!