SoFunction
Updated on 2025-03-09

Detailed explanation of attributes you may not know

Overview

It must be a strict json file, not just an object in js. Many of these properties can be generated through npm-config

name

The most important attributes in this article are the name and version properties. These two attributes are necessary, otherwise the module will not be installed. These two attributes together form a unique identifier of an npm module. While the content in the module is changed, the module version should also be changed. The name attribute is your module name. Here are some naming rules:

  • The name must be less than or equal to 214 bytes, including the prefix name (such as xxx/xxxmodule).

  • The name cannot start with "_" or "."

  • Cannot contain capital letters

  • Name will become part of the url and cannot contain illegal url characters.

    Here are some suggestions from the official website documentation:

  • Do not use the same name as the node core module

  • Do not contain "js" and "node" in the name. It's assumed that it's js, since you're writing a file, and you can specify the engine using the "engines" field. (See below.)

  • The name attribute will become a module url, a parameter in the command line, or a folder name. Any non-url-safe character cannot be used in name, nor can it start with "_" or "."

  • The name attribute may be written in the parameter of require(), so it is best to take a short and semantic value.

  • Before creating a module, you can first go to the subsequent URL to check whether the name has been occupied. /

    • # When publishing a package, you need to check whether a package name existsnpm search <ModuleName>

The name attribute can have some prefixes such as . @myorg/mypackage. You can see the detailed description in the documentation of npm-scope(7).

version

The version must be parsable by a node-semver module that npm depends on. See the dependencies module below for specific rules

description

A description that facilitates others to understand the function of your module and is also useful when searching.

keywords

An array of strings to facilitate others to search for this module

homepage

Project homepage urlNotice:The url and url properties of this project's homepage are different. If you fill in the url properties, the npm registration tool will think that you have posted the project to another place. When obtaining the module, it will not be retrieved from the npm official repository, but will redirect to the address configured by the url property. (The word spit was used in the original document, and the author said he was not kidding :)

bugs

Fill in a bug submission address or an email address. Those who are tricked by your module can complain here, for example:

{
    "url" : "/owner/project/issues",
    "email" : "project@"
}

The url and email can be filled in at will or not. If you only fill in one, you can directly write it into a string instead of an object. If you fill in the url, the npm bugs command will use this url.

license

You should create a protocol for your module so that users know what permissions they have to use your module and what are the limitations of using it. The simplest, for example, you use a protocol like BSD-3-Clause or MIT, as follows:

{ "license" : "MIT" }

You can/licenses/ This address is available in the protocol list.

User-related attributes: author, contributors

author is a coder, and contributors is a coder array. person is an object with some description attributes, as follows:

{
    "name" : "Barney Rubble",
    "email" : "b@",
    "url" : "/"
}

You can also use the following format abbreviation, npm will help convert:

"Barney Rubble b@ (/)"

Both email and url properties can actually be omitted. There is also a maintainers attribute that describes user information.

files

The value of the files attribute is an array, which is the file name or folder name under the module. If it is a folder name, all files under the folder will be included (unless the file is excluded by other configurations). You can also create a .npmignore file in the module root directory (a file starting with "." cannot be created directly under Windows. Use the Linux command line tool to create such as git bash). The files written in this file will be excluded even if they are written in the files attribute. The writing method of this file is similar.

main

The main attribute specifies the main entry file of the program. It means that if your module is named foo, and the user installs this module and uses this module through require("foo"), then the content returned by require is the object pointed to in the file specified by the main attribute. It should point to a file in the module root directory. For large logarithmic modules, this property is more about allowing the module to have a main entrance file, but many modules do not write this property.

bin

Many modules have one or more executable modules that need to be configured in the PATH path. npm makes this work very simple (in fact, npm itself is also installed as an executable command through the bin attribute). If you want to use this function of npm, configure a bin attribute in it. The bin attribute is a map with the command name key and the local file name value as follows:

{
    "bin" : { "myapp" : "./" }
}

When installing the module, if it is installed globally, npm will create a soft link in the bin directory for the files configured in the bin (for Windows systems, the default will be in the C:\Users\username\AppData\Roaming\npm directory). If it is installed locally, a soft link will be created in the ./node_modules/.bin/ directory in the project. Therefore, according to the example above, when you install myapp, npm will create a soft link for the /usr/local/bin/myapp path. If your module has only one executable file and its command name is the same as the module name, you can just write a string instead of the above configuration, for example:

{ 
    "name": "my-program",
    "version": "1.2.5", 
    "bin": "./path/to/program"
}

The function is the same as the following:

{ 
    "name": "my-program", 
    "version": "1.2.5", 
    "bin" : { 
        "my-program" : "./path/to/program" 
    }
}

man

Make a file or make some files through an array to let the man commands under Linux find the document address. If only one file is specified, use the man+ module name directly after installation, regardless of the actual name of the file specified by man. For example:

{
    "name" : "foo",
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "", 
    "man" : "./man/doc.1"
}

Passing the man foo command will get the contents of the ./man/doc.1 file. If the man file name does not start with the module name, the module name will be prefixed during installation. Therefore, the following configuration:

{ 
    "name" : "foo", 
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "", 
    "man" : [ "./man/foo.1", "./man/bar.1" ]
}

Some files will be created as the result of the man foo and man foo-bar commands. The man file must end with a number, or if compressed, end with .gz. The number indicates which part of the file will be installed to.

{ 
    "name" : "foo", 
    "version" : "1.2.3",
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "", 
    "man" : [ "./man/foo.1", "./man/foo.2" ]
}

Two commands: man foo and man 2 foo will be created.

directories

CommonJs uses directories to formulate some methods to describe the structure of a module, and look at the npm file/npm/latest 。

Tell the user where the lib directory is in the module. This configuration has no effect at present, but it is very useful information for those who use the module.

If you specify the bin directory here, the files below this configuration will be added to the bin path. If you have already configured the bin directory in it, the configuration here will not work.

Specify a directory, which contains man files, which is a syntax sugar for configuring man files.

Put some markdown files in this directory, and they may eventually be displayed friendly one day (it should be on the npm website)

Put some sample scripts, maybe it will be useful one day - -!

repository

Specifying a code storage address will help people who want to contribute code to your project. Like this:

"repository" :
  {
      "type" : "git",
      "url" : "/npm/"
  }

"repository" :
  { 
      "type" : "svn", 
      "url" : "/svn/trunk/"
  }

If your module is placed in the GitHub, GitHub gist, Bitbucket, or GitLab repository, you can use the abbreviation tag to complete it when installing npm:

"repository": "npm/npm"
"repository": "gist:11081aaa281"
"repository": "bitbucket:example/repo"
"repository": "gitlab:another/repo"

scripts

The scripts attribute is an object that specifies the commands that need to be executed in each link of the project's life cycle. A key is an event in the life cycle, and a value is the command to be executed. The specific contents include install start stop, etc., see /misc/scripts

config

Used to set up some project configurations that do not change much, such as port, etc. Users can use the following usage:

(...).listen(.npm_package_config_port)

You can modify config through npm config set foo:port 80. See details/misc/config

{ 
    "name" : "foo", 
    "config" : { "port" : "8080" }
}

dependencies

The dependencies property is an object that configures the module list of modules that the module depends on. The key is the module name, the value is the version range, and the version range is a character that can be divided by one or more spaces. Dependencies can also be specified as a git address or a compressed packet address. Do not write test tools or transpilers into dependencies. Here are some writing methods, see/misc/semver

  • version exact match version
  • >version must be greater than a certain version
  • >=version greater than or equal to
  • <version less than
  • <=version version less than
  • ~version "approximately equal", please refer to the semver document for details.
  • ^version "compatible version" details are available in the semver documentation
  • 1. Only one or two.
  • http://... See the following URL as description of denpendencies
    • Any version
  • "" null character, same as *
  • version1 - version2 is equivalent to >=version1 <=version2.
  • range1 || range2 Range2 Range1 and range2 can satisfy either
  • git... See the following git url as an explanation of denpendencies
  • user/repo See below for instructions on GitHub repository
  • A special tag posted by tag, see npm-tag documentation/getting-sta…
  • path/path/path See the description of the local module below. The following writing methods are all OK:
{ "dependencies" :
  { "foo" : "1.0.0 - 2.9999.9999"
  , "bar" : ">=1.0.2 <2.1.2"
  , "baz" : ">1.0.2 <=2.3.4"
  , "boo" : "2.0.1"
  , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
  , "asd" : "/"
  , "til" : "~1.2"
  , "elf" : "~1.2.3"
  , "two" : ""
  , "thr" : "3."
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

URLs as Dependencies

In the version scope, you can write a url pointing to a compressed package. When the module is installed, the compressed package will be downloaded and installed to the module local area.

Git URLs as Dependencies

Git url can be like the following:

git:///user/#commit-ish
git+ssh://user@hostname:#commit-ish
git+ssh://user@hostname/#commit-ish
git+http://user@hostname/project/#commit-ish
git+https://user@hostname/project/#commit-ish

commit-ish can be any label, hash value, or a branch that can be detected, and the default is the master branch.

GitHub URLs

Support the writing of username/modulename of github. # can be added with a suffix to write the branch hash or tag:

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

Local Paths

npm2.0.0 or above can provide a local path to install a local module. It can be installed through npm install xxx --save, and the format is as follows:

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

The generated relative path is as follows:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

This property is useful when offline development or testing requires npm install, and you don't want to create an npm server by yourself, but you should not use this property when publishing modules to public repositories.

devDependencies

If someone wants to download and use your module, maybe they don't want or need to download some additional test or documentation frameworks you use during the development process. In this case, the best way is to add these dependencies to the object of the devDependencies property. These modules will be installed when npm link or npm install, and can also be managed like other npm configurations. See npm config documentation for details. For some cross-platform construction tasks, such as compiling CoffeeScript into JavaScript, you can complete this task by configuring the prepublish script in the script attribute, and then the coffee-script module you need to rely on is written in the devDependencies attribute. For example:

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepublish": "coffee -o lib/ -c src/"
  },
  "main": "lib/"
}

The prepublish script will be run before release, so users no longer need to complete the compilation process by themselves before using it. In development mode, running npm install will also execute this script (see npm script documentation), so it can be easily debugged.

peerDependencies

Sometimes when you do some plug-in development, such as grunt and other tools, they are often developed based on a certain version of grunt, and dependencies such as require("grunt") will not appear in their code, and grunt dependencies will not be written in the dependencies configuration. In order to explain that this module can only run as a plug-in within a certain version of the host, peerDependencies can be configured:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": ""
  }
}

The above configuration ensures that tea-latte will be installed with the version of tea when npm installs, and their dependencies are of the same level: ├── [email protected] └── [email protected] The purpose of this configuration is to let npm know. If you want to use this plug-in module, please make sure that a compatible version of the host module is installed.

bundledDependencies

The above word has less d, and it is also OK to write bundleDependencies. A module that will be packaged together when published.

optionalDependencies

If a dependent module can be used, and you also want npm to continue running when the module cannot be found or cannot be retrieved, you can put this module dependency into the optionalDependencies configuration. The writing method of this configuration is the same as that of dependencies. The difference is that the installation failure of the module written here will not cause the npm install to fail. Of course, this kind of module requires you to handle the actual situation of the module in the code yourself, for example:

try {
  var foo = require('foo')
  var fooVersion = require('foo/').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  ()
}

The configuration in optionalDependencies will override the configuration in dependencies, and it is best to write it in only one place.

engines

You can specify the node version range for which the project runs, as follows: { "engines" : { "node" : ">=0.10.3 <0.12" } } Like dependencies, if you do not specify the version range or specify it as *, any version of node is OK. You can also specify some npm versions to install your module correctly, for example: { "engines" : { "npm" : "~1.0.20" } } It should be noted that unless you set the engine-strict property, the engines property is for reference only.

engineStrict

Note: This property has been deprecated and will be killed in npm version 3.0.0.

os

You can specify which operating system your module can only run on: "os" : [ "darwin", "linux" ] You can also specify a blacklist instead of a whitelist: "os" : [ "!win32" ] The operating system of the service is judged by the origin. This attribute allows black and white lists to exist at the same time, although there is no need to do this...

cpu

The restriction module can only run under a certain CPU architecture "cpu" : [ "x64", "ia32" ] You can also set a blacklist: "cpu" : [ "!arm", "!mips" ] The cpu architecture is judged by

preferGlobal

If your package is primarily used to install to a global command line application, then the value is set to true, and if it is installed locally, a warning is provided. In fact, this configuration does not prevent the user from installing the module locally, but only prevents the module from being used incorrectly to cause some problems.

private

If this property is set to true, npm will refuse to publish it, which is to prevent a private module from being published inadvertently. If you just want the module to be published to a specific npm repository, such as an internal repository, you can configure the repository parameters in the publishConfig below.

publishConfig

This configuration is a collection of some values ​​that will be used when the module is released. If you do not want the module to be marked as the latest by default, or published to a public repository by default, you can configure the tag or repository address here.

DEFAULT VALUES

npm sets some default parameters, such as: ·"scripts": {"start": "node"} If there is a file in the root directory of the module, then npm start will run this file by default. "scripts":{"preinstall": "node-gyp rebuild"} If there is a node-gyp in the root directory of the module, npm will use node-gyp to compile preinstall scripts "contributors" by default: [...] If there is an AUTHORS file in the root directory of the module, npm will parse each line of data in Name (url) format and add it to contributors. You can use # to add line comments.

Reference Document List

  • /
  • semver(7)
  • npm-init(1)
  • npm-version(1)
  • npm-config(1)
  • npm-config(7)
  • npm-help(1)
  • npm-faq(7)
  • npm-install(1)
  • npm-publish(1)
  • npm-rm(1)

Summarize

This is the end of this article about attributes you may not know. For more relevant attribute content, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!