Jj-npm-template NPM

Jack & Jones NPM construction kit

Welcome to the wonderful world of NPM

This starter kit will let you create and publish NPM packages using coffeescript and gulp.

Keep in mind that this published package is worth nothing, since the only thing it does is to log your name and a message to the console. If you actually want to work with this, you'll want to follow the steps below to work with the source and use it as a template for your own package.

How to create your own package

Step 1 - Get the source code

Well, start by grabbing the code from here. It's not enough to just fork or branch it, since we'll be publishing it to the NPM registry later. If you don't copy it, you'll overwrite the template, and we don't want that.

Step 2 - git

After you've copied the code, it's probably a good idea to create a new repo for it so you can version your code. So go do that.

Step 3 - Update package info

Now you should reset the package.json information. I've attached a default version below, which should do the trick. You're welcome to customize it to whatever you need.

{
  "name": "Package name here",
  "version": "0.0.0",
  "description": "Package description here",
  "main": "dist/index.js",
  "license": "MIT",
  "dependencies": {},
  "devDependencies": {
    "del": "^2.2.0",
    "gulp": "^3.9.0",
    "gulp-coffee": "^2.3.1",
    "gulp-coffeelint": "^0.6.0",
    "gulp-plumber": "^1.0.1",
    "gulp-util": "^3.0.7"
  },
  "repository": {
    "type": "git",
    "url": "git+ssh://github.com/user/repo.git"
  },
  "author": "Your name (Or Jack & Jones Tech Team, if you work for us)",
  "bugs": {
    "url": "https://github.com/user/repo/issues"
  },
  "homepage": "https://github.com/user/repo"
}

Step 4 - Install dependencies

Now, in order to develop using this package, you'll need gulp and some coffeescript dependencies. That's pretty straight forward: npm install in the source folder.

Step 5 - Write code!

Now - Go knock yourself out and write code in src/index.coffee. Gulp is here to help you. By using the command gulp it'll tell you what tasks are available for you to run.

How to publish your package

Once you've finished writing your magnificent code, it's time to publish it to the public NPM registry.

Step 1 - Associate your NPM user to your package

You're going to need a user at the NPM registry.

You can either create one by using the npm adduser command, or if you have one already, you can use npm login to associate it to your local package.

More details in the official documentation here

Step 2 - Publish!

After you've done a build of your project, you can go ahead a publish it. Use the npm publish command, and boom - You're rolling!

Now, a quick note - Once you've published a package with a specific version, say 1.0.0, you can't publish to that version again. So once it's done, there's no going back. To get to know versions better, check out the FAQ below.

Step 3 - Use your package

After you publish, it's now available through NPM. So simply go to your project and do npm install name-of-package. In this case npm install jj-npm-template. Now you can require and use it, just like any other NPM package.

FAQ

I have a problem. What do I do?

You either stand up and call Jeppe's name as loudly as possible (Odds are he'll come help you), or you report an issue on github.

I don't understand semantic versioning. Help?

Start by watching this video.

Semantic versioning (or semver) is based on a three number value, using dot notation. For example 1.0.0. Each number represents a type of change.

Patch releases: Bug fixes and minor changes. Patches increment the last number. 1.1.0 -> 1.1.1
Minor releases: New features that don't break exsisting features. Minors increment the middle number. 1.1.0 -> 1.2.0
Major releases: Changes which break backwards compatability or are major rewrites of existing features. 1.1.0 -> 2.0.0

These versions are listed in package.json if you want to update them manually. However NPM makes it easy for us, by using either npm version patch, npm version minor or npm version major. These commands will automatically bump the version.

Note that when you bump a minor or major version, the other values reset. For example 1.5.5 -> 2.0.0 or 1.5.5 -> 1.6.0.

I just published a broken version. Can I fix it?

Well, no. Once you publish a version, it will be locked. If it's broken, you need to publish a new version to fix it.

You have two choices to make the broken version unavailable: deprecate or unpublish. npm deprecate will leave the version available, but prompt user to upgrade. npm unpublish will remove the version completely.

But in general, don't publish broken versions.