Using npm

Basics

Similar to Max Packages, Node provides a mechanism for defining bundles of content. These bundles are called Node Packages. Similar to the Max Package Manager, there is an online repository of user-submitted Node packages. You download and manage these packages using npm, the package manager for Node.js.

npm is a powerful and fully featured tool for Node package management, but you will normally only need it to install packages.

Installing an npm package as a dependency allows you to add functionality to your node.script program. Many popular JavaScript libraries (such as Express) are available as npm packages.

There are three main reasons to bundle content into a package:

To manage dependencies on other packages
To identify the role of various files within the package
To provide metadata about the package, including its version, the authors, and other information

Full documentation for the npm install command can be found here https://docs.npmjs.com/cli/install.html

The package.json File

The package.json file is a JSON formatted main source of information for defining a Node Project and package. It holds critical information like the name, version and main entry point of the package but can also list things like dependencies and/or custom scripts. For a more complete list of options see https://docs.npmjs.com/files/package.json

Run npm init to create this package.json file. You can run reveal to show the file. After you run npm init you should see a package.json file next to your source file.

Once npm init has been run, you can run npm install to gather up any dependencies. These dependencies are added to the package.json file using the npm install -S <package-name> command.

Anatomy of a Node package

package.json

This is a file containing the information about the Node package including the name, its version and its dependencies. It also includes other metadata like the license under which the package is released. For a more complete description see https://docs.npmjs.com/files/package.json

node_modules

This folder contains node dependencies after they have been installed. For more information see “What happens when you install a package?” and “Do you distribute the node_modules folder?”

package-lock.json

This is a file in the JSON file format that contains formatted information about the installed Node dependencies. While package.json specifies dependencies with version ranges as requirements, package-lock.json indicates exactly which dependencies and which versions were actually installed. For more see “What happens when you install a package?”

Everything Else

There are many different ways to organize a Node package. Most packages will have at least some source files. Many will have various scripts that will do things like move files around or verify that source files are valid JavaScript.

How do you find an npm package?

You can use the npm package search at https://www.npmjs.com/, or you can simply use your favorite search engine. Many projects will exist both as a repository on Github, as well as a package in the npm registry.

Once you’ve found a package you want to work with, send the node.script object a message like script npm install <package-name>, replacing <package-name> with the name of the package that you’d like to install.

After installing a package, you should be able to use “require” to include functionality from that package in your code:

const chance = require(“chance”); // Here, chance is the name of an installed package

What happens when you install a package?

Suppose you try to install an npm package by sending a command to a node.script object like script npm install chance

First, npm will generate a dependency tree for the chance package. This contains all of the node packages on which the chance package depends.

Once it has a dependency tree, npm will download all required packages into the node_modules directory.

Simultaneously, npm will generate a package-lock.json file, which indicates exactly which versions of each npm package were downloaded.

If you want, you can delete the node_modules directory. You can then run script npm install without naming any package to reinstall all dependencies based on the contents of package-lock.json. If there is no package-lock.json file, the package.json file will be used instead.

This can be useful for distributing a Max patch with Node dependencies. You shouldn’t need to distribute the node_modules directory, since anyone with an internet connection can regenerate that folder and its contents by running script npm install. If you look at a few Node for Max projects, you will probably encounter a Max patch with a button script npm install and a comment like “You only need to push this once.” That’s because the patch includes a package.json or package-lock.json, but still needs to install its dependencies.

There is an exception: you should include node_modules in any Standalone, Collective or frozen Max for Live Device. See “Do you distribute the node_modules folder?” for more details.

Do you distribute the node_modules folder?

If you’ve worked with Node before, you know that you don’t usually distribute the node_modules folder when you share your work. Rather, you share a package containing a package.json file and the accompanying package-lock.json file. Using the npm ci command you can then install the exact versions of dependency packages as listed in the package-lock.json file

In general, the same is true for Max. If you share a Max patcher or Max project that has a node.script object with npm dependencies, you shouldn’t share the node_modules folder. Instead, share the patcher along with the associated .js file and package.json and package-lock.json. Have a button in your patch that sends the message script npm ci to the node.script object to install dependencies.

There is one exception to this rule, which is when working with a Standalone Application, a Max Collective, or a frozen Max for Live Device. In these cases, you will want to indicate that the contents of node_modules should be included in whatever you export from Max. Detailed instructions can be found here.

Name	Description
Node for Max Documentation - Table of Contents	Node for Max Documentation - Table of Contents
Node for Max - Working with Projects, Devices and Standalones	Node for Max - Working with Projects, Devices and Standalones
node.script

Node for Max - Using npm