About Package.json
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
{
- 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/"
}