-
Notifications
You must be signed in to change notification settings - Fork 279
npm Quick Start Guide
The npm command is the Node.js Package Manager. A package manager is a way to install software written in a particular language or operating system. For example, JavaScript software is often installed with npm and Ruby software with the Gem package manager.
Since kss-node is written as a node.js command-line utility, you'll need Node.js and its npm command installed on your computer.
On Mac OS X, I recommend installing Homebrew, a package manager for installing software on the Mac. And then using brew install node to install Node.js.
- Install Homebrew with:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - Install Node.js with:
brew install node
(I have a monthly reminder to keep all my homebrew packages updated: brew update then brew upgrade. And npm install npm -g and npm up -g to update Node.js global packages after updating homebrew's node.js.)
You can find out how to install Node.js on other operating systems on the Node.js website.
You can test your installation by typing npm list -g --depth 0. That will show you a list of what node.js software you have installed globally. Right now that list should only include npm.
One of the more confusing aspects of npm when you first start using it is the concept of installing something locally versus installing something globally.
The normal applications on your computer (Microsoft Word, Google Chrome) are installed globally. Meaning that if you you open a .doc file, it will open the one version of Microsoft Word on your computer. If you try to open a Word doc you wrote in 1985, it won't work because the version installed on your computer is too new to understand such an old file.
Node.js software gets around this problem by allowing you to install something "locally", meaning that the software will be installed inside a particular folder for use in that folder only.
This allows you to install a new version of software in a new project's folder while you continue to use an older version in another project's folder. For example, Sass 3.2 files don't always compile properly with Sass 3.4, so it would be extremely helpful to have Sass 3.2 installed locally in ~/Sites/myOldClient, while having Sass 3.4 (and its wonderful new features) installed locally in ~/Sites/myNewClient.
Because of how useful it is to install something locally, that is npm's default mode. npm install eslint will install the eslint program into a node_modules folder in the current directory.
# Go to a new project's folder.
> cd myNewProject
# Install eslint into that project.
> npm install eslint
# Run eslint for that project.
> ./node_modules/.bin/eslint path-to-my-js-file.js
# Or use npm's bin command:
> $(npm bin)/eslint path-to-my-js-file.js
Ah, you may have noticed why some people want to install eslint globally. ./node_modules/.bin/eslint is kinda awkward, and $(npm bin) is awkward to remember and type. If you just use npm install -g eslint, npm will install the eslint software globally and you will only have to type the simpler eslint path-to-my-js-file.js.
But, really, don't use the -g option. It looks like npm will eventually ship with an "npm-exec" command so you can type the shorter npm-exec eslint path-to-my-js-file.js. See the npm issue to add npm-exec if you are interested.
In the mean time, you can install the npm-run command globally and then use it to run your local programs.
> npm install -g npm-run
Now you can:
# Install eslint locally
> cd myNewProject
> npm install eslint
# From the project root or any sub-folder...
> cd some/sub/folder
> npm-run eslint file.js
# Check which version of eslint is being used with:
> npm-run which eslint
myNewProject/node_modules/.bin/eslint
As you can see, every time you prefix your command with npm-run, the software used will be the one in myNewProject/node_modules/.bin. Sweet.
If you are going to install more than one node module in a project, you should get into the habit of creating a package.json file per project. The package.json file is a way to keep track of all the software you install for a project and makes it really easy to re-install them.
For example, you can move the package.json to a new folder and then type npm install and npm will read your package.json and install all of the node modules in the new location.
If you aren't copying a package.json file from somewhere else, you can make your own with:
> npm init
npm will prompt you for some basic things like project name. Then you can save the names of your node modules when you install them with:
> npm install --save handlebars
There's one more thing you'll need to understand before we install kss-node, the difference between your application's dependencies and its development dependencies.
For example, your application may require Angular.js to run and may require CSS to run, but it doesn't require the Sass preprocessor. Once the CSS is generated by Sass during development, Sass itself is no longer needed to run the application. So Sass is a development dependency of your application, while Angular is a regular dependency.
You install a normal application dependency with:
> npm install --save angular
And a development dependency with --save-dev:
> npm install --save-dev node-sass
If you look inside your package.json file, you'll see a 'dependencies' and a 'devDependencies' section listing the software you installed with --save and --save-dev.
This last tidbit isn't necessary to use kss-node, but its quick to learn and you'll seem like a npm expert if you remember it.
If you are sharing a project with Git or some other version control system, the package.json will ensure that everyone using the project will have the minimal software requirements (e.g. kss-node 2.0 or later.) However, using a package.json doesn't ensure that everyone is using the exact same versions which can lead to inconsistencies or bugs. You can fix this problem by ensuring your project has a npm-shrinkwrap.json file, which, fortunately, you can easily generate with npm shrinkwrap --dev; then just add that npm-shrinkwrap.json file to Git. When another person checks out the project and runs npm install, npm will read the lengthy npm-shrinkwrap.json file and install the exact same versions of all the dependencies.
# Verify you have nothing but npm installed globally.
> npm list -g --depth 0
# Create a package.json file to keep track of your dependencies.
> npm init
# Install software that is required to run your project.
> npm install --save angular
# Install software that is required to develop your project.
> npm install --save-dev node-sass
# Ensure anyone using this project gets the exact versions of your dependencies.
> npm shrinkwrap --dev
# Install all the dependencies after receiving a project with a package.json and optional npm-shrinkwrap.json:
> npm install