Node.js Packages Header Mastering Node.js, Part 4 Eric W. Greene Microsoft Virtual Academy Header Mastering Node.js, Part 4 Node.js Packages Eric W. Greene Produced by

Course Overview Getting Started with Node.js Understanding Packages Installing & Uninstalling Packages Versioning & Outdated Packages Global Packages & NPM Permissions Updating & Configuring NPM Developing & Publishing with Packages

Getting Started with Node.js The course assumes some basic knowledge of Node.js and the JavaScript programming language To run the examples on your machine, you will need Node.js installed Node.js can be downloaded from here: https://nodejs.org Install version 6 or later If you do not understand the basics of these technologies, then watch the WintellectNOW courses, Introduction to Node.js and Node.js Modules

Node Package Manager (NPM) Commonly referred to simply as NPM, the Node Package Manager is a package management system for the Node.js platform Technically, NPM is not part of the Node.js project, but it is included along with Node.js in the official Node.js installer NPM and Node.js follow different version number paths Also, NPM is a for-profit corporation which provides the public package repository, and other private package hosting services

Node Package Manager (NPM) De-facto standard package manager for Node.js applications and front-end web applications which use Node.js for development tooling Lots useful tools such as Webpack, SASS, TypeScript, Babel, PhantomJS and lots more are distributed as NPM packages NPM supports the distribution packages ranging from simple JavaScript-only packages to complex C++ based packages which require compilation when installed

Node Package Manager (NPM) The public NPM package repository provides a web interface for searching for packages and exploring the details of packages Additionally, the NPM web provides excellent documentation on how to use the NPM command line tool, including… Installing/Uninstall Packages Listing Package Dependencies Checking for Outdated Packages Developing with Packages

NPM Public Repository https://www.npmjs.com/

Understanding Packages Packages can be code libraries, applications or both Typically, your projects themselves will be packages too Packages do not have to be distributed via NPM, and do not have to be publicly available – but they can be if you want A project is a package when it contains a package.json file

The package.json File The package.json file contains metadata about the package including it's name, version, author, description, etc… Additionally, a package.json contains the list of package dependencies that a package needs Listing dependencies is one of the primary benefits of using a package.json file, allowing the package source code to be distributed independent of external packages

Creating a New Package To create a new package, package.json file needs to creating and initialized in the folder where there package has been coded When working with NPM the command line program npm is used To initialized the package.json file, npm is invoked with the init command The init command will prompt the developer with a series of questions concerning the name of the package, author, license, etc.. To skip the questions, and have a package.json file created instantly the –y option can be used

Creating a New Package

Installing / Uninstalling Packages Creating a package.json file is not required to install and uninstall packages, but it is needed if you want to register installed packages as dependencies which can be easily installed again in the future when the project is deployed to another folder or system Typically, packages are installed from the public repository, but it is possible to install packages from a repository local to your corporate network or even from linked packages local to your system Setting up a corporate repository is beyond the scope of this course, but linked packages are discussed in Developing and Publishing Packages

Installing a Package The command npm install <package-name> will install the specified package name If the package should be registered as a production dependency of the package, the –S or –save flags should be specified If the package should be registered as a development dependency of the package, the –D or –save-dev flags should be specified If the package should be registered as an optional dependency of the package, the –O or –save-optional flags should be specified

Restoring Package Dependencies When checking out a Node.js project with a package.json from source control, the node_modules folder is typically missing (generally node_modules is not committed source control) To restore all dependencies, the command npm install with no package name should be used, NPM will read the package.json dependency configuration to restore the packages for the project To restore only the dependencies for running the application in production (no development dependencies) run the npm install command with the --production flag

Peer Dependencies Sets up a relationship between two packages where they are used together but are not dependent upon each other Plugins are the best example, often plugins do not directly depend upon the package they plug into; therefore, they have cannot specify the version of the package they need Peer dependencies allow packages to specify which host package its version that it is designed to work with More Info: https://nodejs.org/en/blog/npm/peer-dependencies/

Installing Scoped Packages Scoped packages are associated with a particular organization Scopes allow an organization's packages to be logically stored together Works well for isolating private packages on NPM When installing scoped packages, the scope is prefixed to the package name All scoped packages are stored in a subfolder of the node_modules folder named after the scope

Installing From Other Sources Most packages are installed from the public NPM repository, or a locally hosted NPM repository Packages can be installed from other sources as well Tarballs – local file or URL to a file Git – including GitHub, BitBucket, GitLab and Gist

Uninstalling Packages Packages can be installed using the npm uninstall <package name> command Uninstalling packages removes all of its dependencies unless those dependencies are used by other packages not being uninstalled To remove a saved dependency from the the package.json file when uninstalling packages include the same save flag as used when the package was installed

Installing and Uninstalling Packages

Versioning and Outdated Packages NPM packages use the semver versioning system Following the "spirit" of semver is the responsibility of the developer, and developers are greatly encouraged to do so The versioning scheme use the following pattern: MAJOR.MINOR.PATCH So version 1.2.3 would be a major version of '1', minor version of '2' and a patch version of '3'

Semantic Versioning http://semver.org/

NPM Recommended Best Practices Projects to be shared publicly should be initially released with a major version of 1 Bug fixes and other minor changes should be released as patch version increments New features which do not break existing features should be released as minor version increment Changes which are not backward compatible should be released as a major version increment More: https://docs.npmjs.com/getting-started/semantic-versioning

Package Dependency Version Number When installing and saving package dependencies, the version of the package is saved in the package.json file Semver provides various patterns to determine what version of a package will satisfy the dependency requirement The default version number scheme indicates that all versions up to, but not including, the next major version can be installed to meet the package dependency requirement Exact version: 1.1.1

Patch, Minor & Major Increments Patch increments up to but not including the next minor version: 1.2 – any 1.2 version up to but not including 1.3 1.2.x - any 1.2 version up to but not including 1.3 ~1.2.3 – any version equal to or greater than 1.2.3 up to but not including 1.3 Minor increments up to but not including the next major version: 1 – any version of 1 up to but not including 2 1.x – any version of 1 up to but not including 2 ^1.2.3 - any version equal to or greater than 1.2.3 up to but not including 2 Major increment "*" or "x" – up to latest version

Checking Outdated Packages The command npm outdated will return a list of packages which are outdated, and could be upgraded To check a specific package, execute npm outdated <package_name> Current – is the current version of package which is installed Wanted – is the highest version package which satisfies the semver version of the package in the package.json file Latest – is the package version in the repository in the tagged with latest

Upgrading Packages The command npm update will update all packages with a newer version within the range specified by the semver Individual packages can be updated using npm update <package_name> When npm update with no package name is used, missing packages will be installed To save the new version numbers to package.json, use the –save and –save-dev flags

Updating Outdated Packages

Global Packages and NPM Permissions In addition to installing packages within packages, package can also be installed globally Installing packages globally on Mac and Linux requires super user permissions or adjusting folder settings for global packages Either the global package folder needs to changed Or the permissions of the default global package folder needs to be changed

Global Packages The vast majority of package installations are local to a project Global packages are primarily limited to executable programs – not code libraries The recent trend has been to not install any packages globally, and instead install executable programs local to each project Exceptions would be generator programs such as yeoman

Managing Global Packages To install packages globally, the –g flag must be used when installing the package To uninstall packages globall, the –g flag must be used when uninstalling the package To see outdated global packages, use the –g flag when running the outdated command To update global packages, use the –g flag when running the package update

Installing Packages Globally

Updating and Configuring NPM NPM can update itself using the following command npm update –g npm NPM supports a number of configuration options The most important options are for configuring proxy servers for downloading packages through a corporate firewall npm config set proxy <some_url> npm config set https-proxy <some_url>

NPM Configuration File Setting configuration options will create a .npmrc file in the user's root folder Project level configuration options can be set through an .npmrc file in the projects root folder Global configuration options can be set in the $PREFIX/etc/npmrc file $PREFIX can be determined by this command: npm config get prefix

NPM Configuration Commands npm config set <key> <value> - sets a configuration value for the configuration key npm config get <key> - gets a configuration value for the configuration key npm config delete <key> - delete the configuration key and value npm config list- list the configuration keys and values

Updating NPM and Setting the Configuration

Developing and Publishing Packages are useful organizing larger projects, or sharing common code between different projects NPM provides a linking feature which allows packages to be developed independently, yet executed together for debugging and testing purposes Once developed, packages can be published to the NPM repository to be distributed to other projects The company, npm, provides both the public repository (for free) and private repos (for a price) for distributing packages

Linking and Unlinking To link two local packages to each other, the npm link command is used To remove a link between two local packages, the npm unlink command is used Each command accepts arguments depending upon the context of the linking and unlinking Linking allows one local package to reference another local package similar to installing a package from the npm repository This eases development and debugging of multiple packages

Linking Packages $ npm link Creates a link to the current package folder from the global package folder $ npm link some-package-name Creates a link to the global package folder from the local package folder $npm link folder-path-to-another-package Create a link to the other package from the global package folder, then link to the global package folder from the current package folder Allows linking to be in one step, instead of two

Linking Packages Linking uses the specific operating system linking features on which npm is being executed On Windows, the link is a directory junction (check out the mklink command) https://technet.microsoft.com/en-us/library/cc753194(v=ws.11).aspx On Mac and Linux, the link is a symbolic link (check out the ln command) http://linuxcommand.org/man_pages/ln1.html

Unlinking Packages $ npm unlink Removes the link to the current package folder from the global package folder $ npm unlink some-package-name Removes a link to the global package folder from the local package folder unlink is an alias of the uninstall command

Linking and Unlinking Packages

Publishing Packages The NPM public repository allows all JavaScript developers to publish the Node.js packages so that all developers can use them To publish packages, an account is required With a paid account, private packages can be published as well NPM enterprise allows for local hosting of packages behind a corporate firewall

Publishing Packages Once a package has been published, it should not be unpublished and removed from the repository Unpublishing will break other which require the packages for completing their own package installs There have been famous incidents of this happening with popular packages in the past http://www.theregister.co.uk/2016/03/23/npm_left_pad_chaos/ Instead of unpublishing, packages should be deprecated

Publishing Packages Since publishing requires an account, the npm tool provides a login command which will log a user into NPM for publishing public and private packages The login command is an alias for adduser In addition to logging in, this command will create an account as well Also, being logged in is required for install packages from private repositories To logout, the npm logout command is used To which account you are logged in with, use npm whoami Naturally, this only works if you are logged in

NPM Account Creation https://www.npmjs.com/signup

NPM Private Packages Repository https://www.npmjs.com/npm/private-packages

Publishing Packages

Conclusion NPM is the package manager for Node.js NPM is a company, a package management standard and a public/private package distribution system Projects are NPM packages if they contain a package.json file Almost all projects should contain a package.json file so that external package dependencies can be tracked NPM can be used to manage many aspects of your project setup including replacing the need for Gulp and Grunt