About
Package.json is used by npm to store metadata for projects published as package.
The package.json 1) files:
- serves as documentation for what packages your project depends on.
- allows you to specify the versions of a package that your project can use using semantic versioning rules.
- makes the build reproducible
Syntax
Mandatory:
- “name”: all lowercase one word, no spaces dashes and underscores allowed
- “version” in the form of x.x.x follows semver spec
Optional:
- main.js: the entry point when the package is used.
- description. The description helps people find your package on npm search. If there is no description field in the package.json, npm uses the first line of the README.md or README instead.
Example:
{
"name": "my_package",
"description": "",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "https://github.com/ashleygwilliams/my_package.git"
},
"keywords": [],
"author": "",
"license": "ISC",
"bugs": {
"url": "https://github.com/ashleygwilliams/my_package/issues"
},
"homepage": "https://github.com/ashleygwilliams/my_package"
"dependencies": {
"my_dep": "^1.0.0"
},
"devDependencies" : {
"my_test_framework": "^3.1.0"
}
}
Properties
Name
A name may have an AT sign as a prefix to set a namespace known as scope
Example:
@somescope/somepackagename
@myorg/mypackage
Type
The type property 2) defines the type of module that the package contains
- module: This package contains ECMAScript modules and may have an import or export statement.
- commonjs: This package contains CommonJS modules and may have a require() statement.
- jsnext:main: This package contains ECMAScript modules and is intended to be used with bundlers like Webpack 2+ and Rollup that support the jsnext:main entry point.
- typings: This package contains TypeScript definition files (*.d.ts) and may have an import or export statement.
For instance, if you choose the module value, you define all .js files in that package as being ES modules.
You still can change the type of module via the extension:
- cjs file are commonJs / Node module
- mjs file are ESM module
Types
The types property is used in the resolution of the location of declaration files.
Typings
Main
main defines the main script
Module
modules defines where to find the ECMAScript-style module 4)
Note that Node uses the type property with the value module.
"module": "src/index.js",
if compiled via typescript
"module": "./dist/index.js",
Browser
browser defines the location of modules that are only available inside the browsers.
"browser": {
"module-a": false,
"./server/only.js": "./shims/server-only.js"
}
PackageManager
Since Node.js 16.x, the packageManager property defines the desired package manager 5).
{
"packageManager": "[email protected]"
}
The installation of the package manager should be done with Corepack (since 16.10) which acts as an intermediary between Node and the package manager as it lets you use different package manager versions across multiple projects (ie without having to check-in the package manager binary anymore).
- Installation before 16.10:
npm i -g corepack
- Enable
corepack enable
Example of Command line with Corepack
"C:\nodejs\\node.exe" "C:\nodejs\\node_modules\corepack\dist\yarn.js" run dev
Resolve
The import order of precedence is defined in resolve-mainfields for webpack
module.exports = {
//...
resolve: {
mainFields: ['browser', 'module', 'main']
}
};
Scripts
The script section of the package.json allows to start command. See What are npm scripts and how to use them ? The script property of Package.json
Dependencies
- Javascript Package - Dependencies: these dependency packages are required by your application in production
devDependencies
- Javascript Package - Dev Dependency: these dependency packages are only needed for development and testing
peerDependencies
Management
Create
yarn init
# optionaly
npm init
Modify Config
npm set init.author.email "[email protected]"
npm set init.author.name "ag_dubs"
npm set init.license "MIT"
Your Name <[email protected]> (http://example.com)
Add dependency
To add dependency, use the save and save dev flag of npm install. See Javascript Package.
- For dependencies
npm install <package_name> --save
- For dev-dependencies (development and testing)
npm install <package_name> --save-dev
Pass the version to your library
How to pass the version to your library
myLib.VERSION = require('../package.json').version;