Using Node.js Modules with Windows Azure applications

This document provides guidance on using Node.js modules with applications hosted on Windows Azure. It provides guidance on ensuring that your application uses a specific version of module as well as using native modules with Windows Azure.

If you are already familiar with using Node.js modules, package.json and npm-shrinkwrap.json files, the following is a quick summary of what is discussed in this article:

Windows Azure Web Sites understand package.json and npm-shrinkwrap.json files and can install modules based on entries in these files.
Windows Azure Cloud Services expect all modules to be installed on the development environment, and the node_modules directory to be included as part of the deployment package.

Note

Windows Azure Virtual Machines are not discussed in this article, as the deployment experience in a VM will be dependent on the operating system hosted by the Virtual Machine.

Note

It is possible to enable support for installing modules using package.jsonor npm-shrinkwrap.jsonfiles on Windows Azure, however this requires customization of the default scripts used by Cloud Service projects. For an example of how to accomplish this, see Windows Azure Startup task to run npm install to avoid deploying node modules

Node.js Modules

Modules are loadable JavaScript packages that provide specific functionality for your application. A module is usually installed using the npm command-line tool, however some (such as the http module) are provided as part of the core Node.js package.

When modules are installed, they are stored in the node_modules directory at the root of your application directory structure. Each module within the node_modules directory maintains its own node_modules directory that contains any modules that it depend on, and this repeats again for every module all the way down the dependency chain. This allows each module installed to have its own version requirements for the modules it depends on, however it can result in quite a large directory structure.

When deploying the node_modules directory as part of your application, it will increase the size of the deployment compared to using a package.json or npm-shrinkwrap.json file; however, it does guarantee that the version of the modules used in production are the same as those used in development.

Native Modules

While most modules are simply plain-text JavaScript files, some modules are platform-specific binary images. These modules are compiled at install time, usually by using Python and node-gyp. One specific limitation of Windows Azure Web Sites is that while it natively understands how to install modules specified in a package.json or npm-shrinkwrap.json file, it does not provide Python or node-gyp and cannot build native modules.

Since Windows Azure Cloud Services rely on the node_modules folder being deployed as part of the application, any native module included as part of the installed modules should work in a cloud service as long as it was installed and compiled on a Windows development system.

Native modules are not supported with Windows Azure Web Sites. Some modules such as JSDOM and MongoDB have optional native dependencies, and will work with applications hosted in Windows Azure Web Sites.

Using a package.json file

The package.json file is a way to specify the top level dependencies your application requires so that the hosting platform can install the dependencies, rather than requiring you to include the node_packages folder as part of the deployment. After the application has been deployed, the npm install command is used to parse the package.json file and install all the dependencies listed.

During development, you can use the --save, --save-dev, or --save-optional parameters when installing modules to add an entry for the module to your package.json file automatically. For more information, see https://npmjs.org/doc/install.html.

One potential problem with the package.json file is that it only specifies the version for top level dependencies. Each module installed may or may not specify the version of the modules it depends on, and so it is possible that you may end up with a different dependency chain than the one used in development.

Note

When deploying to a Windows Azure Web Site, if yourpackage.jsonfile references a native module you will see an error similar to the following when publishing the application using Git:

npm ERR! module-name@0.6.0 install: `node-gyp configure build`
npm ERR! `cmd "/c" "node-gyp configure build"` failed with 1

Using a npm-shrinkwrap.json file

The npm-shrinkwrap.json file is an attempt to address the module versioning limitations of the package.json file. While the package.json file only includes versions for the top level modules, the npm-shrinkwrap.json file contains the version requirements for the full module dependency chain.

When your application is ready for production, you can lock-down version requirements and create an npm-shrinkwrap.json file by using the npm shrinkwrap command. This will use the versions currently installed in the node_modules folder, and record these to the npm-shrinkwrap.json file. After the application has been deployed to the hosting environment, the npm install command is used to parse the npm-shrinkwrap.json file and install all the dependencies listed. For more information, see https://npmjs.org/doc/shrinkwrap.html.

Note

When deploying to a Windows Azure Web Site, if yournpm-shrinkwrap.jsonfile references a native module you will see an error similar to the following when publishing the application using Git:

npm ERR! module-name@0.6.0 install: `node-gyp configure build`
npm ERR! `cmd "/c" "node-gyp configure build"` failed with 1

Next Steps

Now that you understand how to use Node.js modules with Windows Azure, learn how to specify the Node.js version, build and deploy a Node.js Web Site, and How to use the Windows Azure Command-Line Tools for Mac and Linux.