Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
npm Quick Start Guide
Installing Node.js and npm
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.
Installing globally vs. locally
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
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
Installing a bunch of node modules in a project
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
> 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
Sharing a project
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.
npm commands: a recap
# 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