[pve-eslint.git] / eslint / docs / src / developer-guide / package-json-conventions.md

---
title: Package.json Conventions
layout: doc
edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/package-json-conventions.md
---

The following applies to the "scripts" section of `package.json` files.

## Names

npm script names MUST contain only lower case letters, `:` to separate parts, `-` to separate words, and `+` to separate file extensions. Each part name SHOULD be either a full English word (e.g. `coverage` not `cov`) or a well-known initialism in all lowercase (e.g. `wasm`).

Here is a summary of the proposal in EBNF.

```ebnf
name = life-cycle | main ":fix"? target? option* ":watch"?

life-cycle = prepare | preinstall | install | postinstall | prepublish | preprepare | prepare | postprepare | prepack | postpack | prepublishOnly;

main = "build" | "lint" | "start" | "test";

target = ":" word ("-" word)* | extension ("+" extension)*;

option = ":" word ("-" word)*;

word = [a-z]+;

extension = [a-z0-9]+;
```

## Order

The script names MUST appear in the package.json file in alphabetical order. The other conventions outlined in this document ensure that alphabetical order will coincide with logical groupings.

## Main Script Names

With the exception of [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts) all script names MUST begin with one of the following names.

### Build

Scripts that generate a set of files from source code and / or data MUST have names that begin with `build`.

If a package contains any `build:*` scripts, there MAY be a script named `build`. If so, SHOULD produce the same output as running each of the `build` scripts individually. It MUST produce a subset of the output from running those scripts.

### Lint

Scripts that statically analyze files (mostly, but not limited to running `eslint` itself) MUST have names that begin with `lint`.

If a package contains any `lint:*` scripts, there SHOULD be a script named `lint` and it MUST run all of the checks that would have been run if each `lint:*` script was called individually.

If fixing is available, a linter MUST NOT apply fixes UNLESS the script contains the `:fix` modifier (see below).

### Start

A `start` script is used to start a server. As of this writing, no ESLint package has more than one `start` script, so there's no need `start` to have any modifiers.

### Test

Scripts that execute code in order to ensure the actual behavior matches expected behavior MUST have names that begin with `test`.

If a package contains any `test:*` scripts, there SHOULD be a script named `test` and it MUST run of all of the tests that would have been run if each `test:*` script was called individually.

A test script SHOULD NOT include linting.

A test script SHOULD report test coverage when possible.

## Modifiers

One or more of the following modifiers MAY be appended to the standard script names above. If a target has modifiers, they MUST be in the order in which they appear below (e.g. `lint:fix:js:watch` not `lint:watch:js:fix`)

### Fix

If it's possible for a linter to fix problems that it finds, add a copy of the script with `:fix` appended to the end that also fixes.

### Target

The name of the target of the action being run. In the case of a `build` script, it SHOULD identify the build artifact(s), e.g. "javascript" or "css" or "website". In the case of a `lint` or `test` script, it SHOULD identify the item(s) being linted or tested. In the case of a `start` script, it SHOULD identify which server is starting.

A target MAY refer to a list of affected file extensions (such as `cjs` or `less`) delimited by a `+`. If there is more than one extension, the list SHOULD be alphabetized. When a file extension has variants (such as `cjs` for CommonJS and `mjs` for ESM), the common part of the extension MAY be used instead of explicitly listing out all of the variants (e.g. `js` instead of `cjs+jsx+mjs`).

The target SHOULD NOT refer to name of the name of the tool that's performing the action (`eleventy`, `webpack`, etc.)

### Options

Additional options that don't fit under the other modifiers.

### Watch

If a script watches the filesystem and responds to changes, add `:watch` to the script name.
Commit	Line	Data
8f9d1d4d DC	1	---
	2	title: Package.json Conventions
	3	layout: doc
	4	edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/package-json-conventions.md
	5	---
	6
	7	The following applies to the "scripts" section of `package.json` files.
	8
	9	## Names
	10
	11	npm script names MUST contain only lower case letters, `:` to separate parts, `-` to separate words, and `+` to separate file extensions. Each part name SHOULD be either a full English word (e.g. `coverage` not `cov`) or a well-known initialism in all lowercase (e.g. `wasm`).
	12
	13	Here is a summary of the proposal in EBNF.
	14
	15	```ebnf
	16	name = life-cycle \| main ":fix"? target? option* ":watch"?
	17
	18	life-cycle = prepare \| preinstall \| install \| postinstall \| prepublish \| preprepare \| prepare \| postprepare \| prepack \| postpack \| prepublishOnly;
	19
	20	main = "build" \| "lint" \| "start" \| "test";
	21
	22	target = ":" word ("-" word)* \| extension ("+" extension)*;
	23
	24	option = ":" word ("-" word)*;
	25
	26	word = [a-z]+;
	27
	28	extension = [a-z0-9]+;
	29	```
	30
	31	## Order
	32
	33	The script names MUST appear in the package.json file in alphabetical order. The other conventions outlined in this document ensure that alphabetical order will coincide with logical groupings.
	34
	35	## Main Script Names
	36
	37	With the exception of [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts) all script names MUST begin with one of the following names.
	38
	39	### Build
	40
	41	Scripts that generate a set of files from source code and / or data MUST have names that begin with `build`.
	42
	43	If a package contains any `build:*` scripts, there MAY be a script named `build`. If so, SHOULD produce the same output as running each of the `build` scripts individually. It MUST produce a subset of the output from running those scripts.
	44
	45	### Lint
	46
	47	Scripts that statically analyze files (mostly, but not limited to running `eslint` itself) MUST have names that begin with `lint`.
	48
	49	If a package contains any `lint:` scripts, there SHOULD be a script named `lint` and it MUST run all of the checks that would have been run if each `lint:` script was called individually.
	50
	51	If fixing is available, a linter MUST NOT apply fixes UNLESS the script contains the `:fix` modifier (see below).
	52
	53	### Start
	54
	55	A `start` script is used to start a server. As of this writing, no ESLint package has more than one `start` script, so there's no need `start` to have any modifiers.
	56
	57	### Test
	58
	59	Scripts that execute code in order to ensure the actual behavior matches expected behavior MUST have names that begin with `test`.
	60
	61	If a package contains any `test:` scripts, there SHOULD be a script named `test` and it MUST run of all of the tests that would have been run if each `test:` script was called individually.
	62
	63	A test script SHOULD NOT include linting.
	64
65	A test script SHOULD report test coverage when possible.
66
67	## Modifiers
68
69	One or more of the following modifiers MAY be appended to the standard script names above. If a target has modifiers, they MUST be in the order in which they appear below (e.g. `lint:fix:js:watch` not `lint:watch:js:fix`)
70
71	### Fix
72
73	If it's possible for a linter to fix problems that it finds, add a copy of the script with `:fix` appended to the end that also fixes.
74
75	### Target
76
77	The name of the target of the action being run. In the case of a `build` script, it SHOULD identify the build artifact(s), e.g. "javascript" or "css" or "website". In the case of a `lint` or `test` script, it SHOULD identify the item(s) being linted or tested. In the case of a `start` script, it SHOULD identify which server is starting.
78
79	A target MAY refer to a list of affected file extensions (such as `cjs` or `less`) delimited by a `+`. If there is more than one extension, the list SHOULD be alphabetized. When a file extension has variants (such as `cjs` for CommonJS and `mjs` for ESM), the common part of the extension MAY be used instead of explicitly listing out all of the variants (e.g. `js` instead of `cjs+jsx+mjs`).
80
81	The target SHOULD NOT refer to name of the name of the tool that's performing the action (`eleventy`, `webpack`, etc.)
82
83	### Options
84
85	Additional options that don't fit under the other modifiers.
86
87	### Watch
88
89	If a script watches the filesystem and responds to changes, add `:watch` to the script name.