About Package.json

Check out our super awesome package.json generator!
You may be wondering why we use package.json so heavily... from our FAQ:
Why do projects require a package.json file?

Rather than having project maintainers constantly re-entering meta-data about their projects, such as the name, version number, dependencies, etc. every time they want to upload a new package (or version), we thought it would be best to simply keep a file in the project's source that contains the structured meta-data for the project. Then you simply need to bump the version number in the file and save it, before uploading the new release. It's like a Ruby gemspec for JavaScript projects.

And as it turns out, a spec for such a structured meta-file already exists as part of the CommonJS movement and has been adopted by projects such as NodeJS. That file is called package.json. We decided we liked it and that it wouldn't be a bad thing if all JavaScript projects adopted it.

Read more about the package.json spec

We don't currently parse everything in the package.json spec, but we're working on it. Right now, here is what we do:

Sample package.json

Hover over each section for explanation. (the red sections are required for a valid package.json)
{
String for name and [short] description

The release will be added to the existing project by this name. A new project will be created if necessary.

  "name": "EasyTabs",
  "description": "The jQuery EasyTabs plugin handles all of the functionality of tabs and none of the styling.",
String for version number of the new release

The format is "major.minor.patch.qualifier". E.g. "1.2", "3.1.0.rc1"

Qualifying versions (such as release candidates) will not become the default version for download.

  "version": "2.0.1",
Array of keywords

Tags, which will help to categorize your project. For best results, stick with 1-3 keywords.

  "keywords": [
    "tabs"
  ],
Array of maintainers

Each maintainer is an object containing key/value pairs, minimally including name and email.

The email determines which JSPkg users can manage the project and upload new releases.

If maintainers is excluded from the package.json, it will be assumed that you are the only maintainer.

  "maintainers": [
    {
      "name": "Steve Schwartz",
      "email": "steve@alfajango.com",
      "web": "http://www.alfajango.com/blog"
    }
  ],
Array of contributors

This is a list of people who have authored the project. The structure is the same as for the maintainers.

Unlike maintainers, you are not automatically assumed to be a contributor.

  "contributors": [
    {
      "name": "Steve Schwartz",
      "email": "steve@alfajango.com",
      "web": "http://www.alfajango.com/blog"
    },
    {
      "name": "Doug Drouillard",
      "email": "doug@example.com",
      "web": "http://www.example.com/blog"
    }
  ],
Object containing project dependencies

Each dependency object is a list of key/value pairs, where the key is the normalized (i.e. lower-case and hyphens only) name of the dependency, and the value is the specific version of the dependency (or an empty string).

Dependecy types include runtime (dependencies), optional (optionalDependencies), and test (testDependencies).

  "dependencies": {
    "jquery": "1.4"
  },
  "optionalDependencies": {
    "hashchange": "",
    "address": ""
  },
Array of demo/example file paths

If the project contains HTML demo files, include a list of the file paths here. The paths should be relative to the package.json file (in the root).

The site will automatically display these inside an iFrame on the "Live Demos" page, with all JavaScript and stylesheet dependencies and images loaded.

  "demos": [
    "/examples/basic.html",
    "/examples/all_options.html"
  ],
Object containing info for reporting bugs

An object specifying where bugs and issues should be reported. Preferrably includes at least the web attribute.

  "bugs": {
    "mail": "support@alfajango.com",
    "web": "https://github.com/jangosteve/jquery-easytabs/issues"
  },
Array of source code repositories

Each item in the array is an object with attributes 'type' and 'url'.

The 'type' should be 'git', 'svn', or 'hg'.

The 'url' is the direct URL to the source control repository.

  "repositories"	: [
    {
      "type": "git",
      "url": "https://github.com/jangosteve/jquery-easytabs.git"
    }
  ],
Array of licenses

An array of objects, one per license that apply to this project. Each object has a 'name' and 'url' attribute.

  "licenses": [
    {
      "name": "MIT",
      "url": "http://www.opensource.org/licenses/mit-license.php"
    }
  ],
String

URL string for the project's website.

  "homepage": "http://www.alfajango.com/blog/jquery-easytabs-plugin/"
}