diff options
author | isaacs <i@izs.me> | 2010-06-26 11:32:23 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2010-06-26 11:32:23 +0400 |
commit | da9eb9a7f3dfa1b5aa055ea6c6ad4f60c436eb13 (patch) | |
tree | e9b73369f2124aa12ca6488e46cc2ba75c91b441 /doc | |
parent | cea2bf8615fa4737a92b3bf6b5a9bc91a73511df (diff) |
Update json docs to be more comprehensive. Fix #45
Diffstat (limited to 'doc')
-rw-r--r-- | doc/json.md | 138 |
1 files changed, 98 insertions, 40 deletions
diff --git a/doc/json.md b/doc/json.md index 3cd417171..80d6fb018 100644 --- a/doc/json.md +++ b/doc/json.md @@ -8,56 +8,82 @@ npm aims to implement the commonjs adjustments have been made, which may eventually be unmade, but hopefully will be incorporated into the spec. -## overlay - -npm responds to the `node` and `npm` env-specific package.json values, which -you can hang on any of the following keys: `"overlay", "env", "context", -"ctx", "vnd", "vendor"`. - -For example: +This document is all you need to know about what's required in your package.json +file. - { "name" : "foo" - , "version" : 7 - , "description" : "generic description" - , "overlay" : - { "node" : - { "name" : "bar" - , "description" : "description for node" - } - , "npm" : - { "version" : "1.0.7" - , "description" : "description for npm" - } - , "narwhal" : - { "description" : "description for narwhal" } - } - } +## name -In this case, this is what npm will treat it as: +The *most* important things in your package.json are the name and version fields. - { "name" : "bar" - , "version" : "1.0.7" - , "description" : "description for npm" - } +The name is what your thing is called. Some tips: -This way, even if npm is not exactly the same as some other package management -system, you can still use both, and it can be a happy planet. +* Don't put "js" or "node" in the name. It's assumed that it's js, since you're + writing a package.json file, and you can specify the engine using the "engines" + field. (See below.) +* The name ends up being part of a URL, an argument on the command line, and a + folder name. So, don't use characters that are annoying in those contexts, like + funny UTF things or parentheses or slashes, or else it'll break. +* The name will probably be passed as an argument to require(), so it should + be something short, but also reasonably descriptive. +* You may want to check the npm registry to see if there's something by that name + already, before you get too attached to it. http://registry.npmjs.org/ ## version +The *most* important things in your package.json are the name and version fields. + Version must be [semver](http://semver.org)-compliant. npm assumes that you've -read the semver page, and that you comply with it. Versions packages with -non-semver versions will not be installed by npm. It's just too tricky if you -have more than one way to do it, and semver works well. +read the semver page, and that you comply with it. Here's how it deviates from +what's on semver.org: -(This is actually mentioned in the Packages/1.0 spec, but it's worth -mentioning that npm enforces this requirement quite strictly, since it's -pretty liberal about most other things.) +* Versions can start with "v" +* A numeric item separated from the main three-number version by a hyphen + will be interpreted as a "build" number, and will *increase* the version. + But, if the tag is not a number separated by a hyphen, then it's treated + as a pre-release tag, and is *less than* the version without a tag. + So, 0.1.2-7 > 0.1.2-6 > 0.1.2 > 0.1.2beta -## dependencies +This is a little bit confusing to explain, but matches what you see in practice +when people create tags in git like "v1.2.3" and then do "git describe" to generate +a patch version. (This is how node's versions are generated, and has driven this +design.) + +## main + +The main field is a module ID that is the primary entry point to your program. +That is, if your package is named `foo`, and a user installs it, and then does +`require("foo")`, then your main module's exports object will be returned. + +This should be a module ID relative to the root of your package folder. + +For most modules, it makes the most sense to have a main script. + +## directories + +The "directories" member is an object hash of folders. + +### directories.lib + +The only directory that npm cares about is the "lib" directory. This is a folder +that will be mapped to the package name. So, if you had a package named `foo`, +and the package.json contains `"directories":{"lib":"./lib"}`, and there was +a file called `./lib/bar.js`, then require("foo/bar") would include that module. -The Packages/1.0 spec's method for specifying dependencies is Unclean in My -Sight. So, npm is using a very simple semver-based method. +This is handy if your package is a collection or library full of useful goodies. +However, dependency paths are not corrected for modules in the lib folder, so it's +a bit more complicated. + +Most of the time, delving into a package's folder is not as awesome. + +## scripts + +The "scripts" member is an object hash of script commands that are run +at various times in the lifecycle of your package. The key is the lifecycle +event, and the value is the command to run at that point. + +See `npm help scripts` to find out more about writing package scripts. + +## dependencies Dependencies are specified with a simple hash of package name to version range. The version range is EITHER a string with has one or more @@ -157,4 +183,36 @@ So, when you install npm, it'll create a symlink from the `cli.js` script to `/usr/local/bin/npm-version`. Then, when you activate that version, it'll create a symlink from `/usr/local/bin/npm-version` to `/usr/local/bin/npm`. -(props to [mikeal](http://github.com/mikeal) for the idea) +## overlay + +npm responds to the `node` and `npm` env-specific package.json values, which +you can hang on the "overlay" key. + +For example: + + { "name" : "foo" + , "version" : 7 + , "description" : "generic description" + , "overlay" : + { "node" : + { "name" : "bar" + , "description" : "description for node" + } + , "npm" : + { "version" : "1.0.7" + , "description" : "description for npm" + } + , "narwhal" : + { "description" : "description for narwhal" } + } + } + +In this case, this is what npm will treat it as: + + { "name" : "bar" + , "version" : "1.0.7" + , "description" : "description for npm" + } + +This way, even if npm is not exactly the same as some other package management +system, you can still use both, and it can be a happy planet. |