|
| 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. |
0 commit comments