SPFx — npm and nodejs commands

Image courtesy : npsjs.com

One of the critical part in building SharePoint Framework solution is to be aware about development tool chain. Since this modern tool chain is completely new for SharePoint developers who have experience in Server side development and Visual Studio as development platform, we will cover each part of this tool chain. We will cover 20% of the core of each component that we will be using 80% of time to become productive immediately.

With popularity of nodejs and JavaScript, Microsoft has also embraced these advances in open source tools and baked these components in SharePoint Framework tool chain. In this post, we will understand what Node.js is how to use npm for SharePoint Framework projects.

Node.js is server side run-time environment for running JavaScript. Node.js has its own ecosystem of packages for building enterprise grade application using JavaScript as server side programming language. SharePoint Framework uses Node.js as development platform. The dependency on Node.js for SharePoint Framework is merely as build platform, for building, debugging and testing environment. There is no other dependency on Node.js for releasing the code to SharePoint environment.

npm stands for Node Package Manager. It is nuget in Node.js world. npm is used for managing packages in your Node.js based applications. It is critical to learn npm to manage package that we will be using for building SharePoint Framework solutions. Prerequisite for testing these commands is to have Node.js installed. You can download LTS installed from official Node.js site . Lets quickly view some useful npm commands that we will need:

npm help

Generic help for npm

npm -h

Get help for a command : npm command-name -h

npm install -h

If you are finding difficulty in commands to use for a specific task, try searching for command using help-search

npm help-search "update"

The above help search will search all the commands relevant to update.

Initializing

You can initiate a new Node.js project using npm init. This will start a wizard and will ask you to some inputs for creating a new project.

npm init

Installing a package

There are various parameters that you can pass when installing a new package.

npm install package-name will install latest version of the package.

npm install typescript

If you wish to install package globally, so that other projects can also use this package, use -g flag.

npm install typescript -g

If you want your package to be saved as a dependency for your project, you need to use save flag while installing.

npm install typescript --save

These dependencies will be added in package.json file which is the default configuration file for any Node.js based project.

If you want to use package only for debugging or testing and the package will not be a part of actual production release, use save-dev. This is cleaner way for adding dependencies that are only required during build process.

npm install typescript --save-dev

You may want to install a specific version of a package sometimes due to compatibility issues, just use version number along with package name.

npm install typescript@2.1.1

Uninstalling a package

You may need to uninstall some of packages which are no longer needed, or you are using some other package.

npm uninstall typescript

This will uninstall typescript package. But if you have added a package as either dependency or dev dependency, you will have to remove these package reference from package.json file as well. To remove package from dependencies section, use “save” or “save-dev”.

npm uninstall typescript --save  
npm uninstall typescript --save-dev

If you have installed a package globally, use -g flag to uninstall.

npm uninstall typescript -g

List Installed packages

To quickly check the packages that you have installed, use list command

npm list

This will however, will generate complete tree of installed packages. If you are not concerned about the packages that are not direct dependencies of your project, use depth flag to filter.

npm list --depth 0

— depth 0 will show you only the list of packages that you have installed and will hide the packages that are installed as dependencies to parent packages. Upgrading packages is very similar to installing and uninstalling so we will skip this part.

Versioning

One of the critical part to understand related to npm packages is versioning used by packages and how install and upgrade will behave when new versions are available. for understanding versioning for package, consider below excerpt from a package.json file.

{
    "dependencies": {
        "@microsoft/sp-client-base": "^1.0.0",
        "@microsoft/sp-core-library": "~1.0.0",
        "@microsoft/sp-webpart-base": "1.0.0",
        "@types/webpack-env": ">=1.12.1 <1.14.0",
        "@microsoft/sp-build-web": "x"
    }
}

Version for package consists of 3 parts, first part represents major version,second part represents minor version and third part represents bug fixes or changes related to performance improvement, cleanup etc.

For @microsoft/sp-client-base, version is “¹.0.0” . This says that currently installed version is 1.0.0, In future if we upgrade or install the package again, npm will be get us the latest package whose version will be 1.x.x. Simply put, if we use carrot (^) before version number, we are instructing npm that keep the major version same as current version, get me the latest minor version available in npm repository and for this minor version, get me the latest bug fixed version.

For @microsoft/sp-core-library, version is “~1.0.0”, means when an update is available, latest package installed will be 1.0.x, this will make sure that your project does to automatically upgrade to higher minor version. You have to perform this upgrade minor version by changing version number to use manually. This tilda (~) will make sure minor version for your package is not updated automatically.

@microsoft/sp-webpart-base does not have caret(^) or tilde(~), instead exact version number. npm will always install this version irrespective of the latest available version. This setting is useful in mission critical application where you can not allow npm to upgrade version before you have tested it. And finally you can simple put ‘x’, which will say get me latest available version.

Understanding these versioning is important because as you develop, you may face compatibility issues for some packages due to versioning. This little understanding on how to go to fix versioning will hopefully save you a lot of time! Check out official npm documentation for commands here.