0 comment

Use `npm version` to upgrade the version of your SPFx solution

When you like to version your SPFx solutions correctly, then it is not enough to upgrade only the ‘package-solution.json’ in the config folder. You might also want to upgrade the ‘package.json’ file with a corresponding version number too.

Besides, there is another component that indicated the version of your solution and is related to git. You want to have to tag containing the version in git too. Later you know precisely what code at that specific point in time was checked available.

Versions documented in the git history

There is no need to update these versions and add the tag manually because this can get automated. It finds its way in the next version of the ‘Pattern and Practice SPFx generator‘.

Step 1 – How ‘npm version’ works

Before we can create a script or tool that injects the package version into the ‘package-solution.json’ file, let us take a short look in the command named ‘npm version‘. When this command gets executed, the next logical version gets written to the ‘package.json’ file. Besides the ‘version’ argument you need to pass in additional ones. Here is a short overview.

npm version major Set a major version and upgrades the ‘package.json’ to v1.0.0, v2.0.0, …

npm version minor Set a minor version and upgrades the ‘package.json’ to v1.1.0, v1.2.0, v1.3.0, …

npm version patch Set a minor version and upgrades the ‘package.json’ to v1.1.1, v1.1.2, v1.1.3, …

Step 2 – Create a tools folder and ‘pre-version.js’ file

First, create a ‘tools’ folder and add a ‘pre-version.js’ inside this folder.

Tools folder containing the pre-version script

Tools folder containing the pre-version script

In future, you like to include maybe more scripts that help automate tasks in your project. The real importance is the content of this script.

Step 3 – Create a pre-version script

In the npm script sections of the ‘package.json,’ many event handlers are available and configurable. One of that event handler is the ‘perversion’ option. So we need to create a script that has the following goals or steps.

  1. Get next version before it gets written to the ‘package.json’ file
  2. Read the ‘./config/package-solution.json’ file
  3. Write the next version to this file.
  4. Save the modification back to the disk file to disk

This is the source code that manages exactly all those steps.

// check if the version numbber gets passed in
// the third option
if (process.argv.length !== 3) {
  console.log('ERROR: No version have been passed in.');

// get the version passed in as argument
const nextVersion = process.argv[2]
  .split('-')[0]; // just in case of preminor, preemajor remove after third digit.

// require filesystem instanc
const fs = require('fs');

// define path to package-solution file
const solution = './config/package-solution.json';

// read package-solution file
const solutionFileContent = fs.readFileSync(solution, 'UTF-8');
// parse file as json
const solutionContents = JSON.parse(solutionFileContent);

// set property of version to next version
solutionContents.solution.version = nextVersion + ".0";

// save file
  // convert file back to proper json
  JSON.stringify(solutionContents, null, 2),

It is a JavaScript that is not intended to run in a browser. Instead, it needs to get executed through ‘NodeJS’.

Step 3 – add pre-version script to pacckage.json

Now the tricky part. How can you detect the change of the version before it gets updated in the ‘package.json’?

Teased already before the “npm-script” section inside the ‘package.json’ file is there to help. It allows you not only to register custom scripts as you need them but there are also some predefined actions.

One of that script handles is “pre-version” that executes a script before a new version number get written to the package file. To execute the previously created script, edit the ‘package.json’ file an add the following line.

On macOS, Linux:

     script: {
         "preversion": "node ./tools/pre-version.js $npm_package_version",

On Windows: thanx to Julie Turner

     script: {
         "preversion": "node ./tools/pre-version.js %npm_package_version%",

A NodeJS executes this way the ‘pre-version.js’ javascript. The additional argument ‘$npm_package_version’ contains already the new upcoming version number. After the ‘package-solution.json’ file was updated with the new version number. The version number also get updated in the ‘package.json’ file.

Final thoughts

This way you don’t have to update the package version in the npm package as well as the package-solution file manually. It is another way to make your life easier but you get more out of it. Whenever you use “npm version” in addition to this command and if a git repository gets configured on your current project. Automatically you get a new tag that gets added to git repository to reference at this specific point in time of your project. (More on git tagging)

BONUS: Create a new distribution build after version upgrade

Unlink “pre-version” another script handle is “postversion” that occurs after the version upgrade happened. You can create for example a new distribution build automatically through the previously described “gulp dist” method.

Just add another script entry like this in the ‘package.json’ is required for that.

  "script": {
    "postversion": "gulp dist"

This way you not only have all the version information updated but you also get a new distribution build.