Semantic Versioning (major.minor.patch)
- Major represents substantial changes to package that may break the existing code.
- Minor represents non-breaking changes.
- Patch represents no interface changes.
Package.json contains dependencies in SPFx solution as below:
Caret dependency: Any version up to (but not including) is accepted
Example: ^3.2.1 means greater than or equal to 3.2.1 but less than 4.0.0
Tilde dependency: It is like Caret dependency, but the range is narrower
Example: ~3.2.1 means greater than or equal to 3.2.1 but less than 3.3.0
Exact dependency: Constrained to a specific version
Example: 3.2.1 means 3.2.1 only
Specifying dependencies and devDependencies in a package.json file
To specify the packages your project depends on, you must list them as
"devDependencies" in your package’s
package.json file. When you (or another user) run
npm install, npm will download dependencies and devDependencies that are listed in
package.json that meet the semantic version requirements listed for each.
- “dependencies”: Packages required by your application in production.
- “devDependencies”: Packages that are only needed for local development and testing.
Lock Down the Package version
When a package is added to SPFx solution using “npm install” command, the package is downloaded and installed to the solution. It is placed under “node_modules” folder and entry of it is recorded in package.json file. Adding –save flag to “npm install” command ensure that the dependency is recorded to package.json. If any developer re-runs “npm install” or “npm update” on this SPFx solution, NPM will download package of appropriate version. It is always recommended to specify –save or –save-exact while running “npm install” command to record and track the dependencies.
If –save flag is not specified, then it will not record the entry in package.json and can cause code to fail because of missing packages. TypeScript compiler might throw an error “Cannot find module”.
“–save-exact” will avoid caret or tilde dependencies only at first level, which makes difficult to get the exact build unless we check-in entire “node_modules” folder to source control.
Freeze the entire tree of dependencies
“npm shrinkwrap” command will help you to freeze the entire tree of dependencies. It creates a JSON file called “npm-shrinkwrap.json” which records exact version of each package used in the solution. It is important in the production environment that same versions of packages get installed as that used during development.
Because of using “npm shrinkwrap”, if “npm install” or “npm update” commands are used against the solution containing “npm-shrinkwrap.json” will restore the exact version of packages and avoids code break issues for other developers.
To find out the outdated packages in the solution, run below command:
Updating npm-shrinkwrap.json file
To update single package version run below command:
npm update <package_name>
Re-run “npm shrinkwrap” command to update npm-shrinkwrap.json file.
It is recommended to re-run “npm shrinkwrap” every time as it will record exact version of package dependencies. This will allow you to rebuild solution on any machine even though newer versions of used packages are released in future and solution is secured using source control.