Repository navigation
[RRFC] format package.json based on config values #423
Description
Motivation ("The Why")
Allow package.json to be formatted according to a set of config values. This will establish default config values for how package.json is written and add a command to rewrite an existing package.json files based on those config values. Since these config values will live in an .npmrc file, it will allow for users to format their package.json differently per project or globally.
Example
# New subcommand in `npm pkg` to format `package.json` based on config values
npm pkg format [--dry-run]
# Any command that writes to `package.json` will do so based on the config values
# All of these could update any part of `package.json` if the relevant configs are set
npm install foo
npm pkg set foo="bar
npm init --yesHow
In the initial implementation, default config values will be set to mirror current behavior where possible, with the goal being that formatting during commands that write to package.json will not be a breaking change.
Sorting will be done via localeCompare.
Configs
pkg-format-indent- Specifies how the file will be indented. If the value is an integer, spaces will be used.
- Defaults to
current(current|n|tabs) - Defaulting to
currentis new behavior based on the discussion in [RRFC] Don't expand tabs by default #420. To not have this change any behavior, the default would be2.
pkg-format-eol- Specifies what the line endings in the file will be
- Defaults to
current(current|lf|cr|crlf) - Defaulting to
currentis new behavior based on the discussion in [RRFC] Don't expand tabs by default #420. To not have this change any behavior, the default would belf.
pkg-format-sort-children- Specifies which top level items will have their children sorted
- If the item is an object, it will be sorted by key. If the item is an array of strings, it will be sorted by string. Otherwise it will be ignored.
- Defaults to
dependencies,devDependencies,peerDependencies,optionalDependencies
pkg-format-keys-start- Specifies a list of top level keys that will always be moved to the start of
package.json - Defaults to ``
- Specifies a list of top level keys that will always be moved to the start of
pkg-format-keys-end- Specifies a list of top level keys that will always be moved to the end of
package.json - Defaults to ``
- Specifies a list of top level keys that will always be moved to the end of
pkg-format-keys-sort- Specifies whether other top level keys not specified by
keys-startandkeys-endwill be sorted - Defaults to
false(true|false)
- Specifies whether other top level keys not specified by
Open Questions
- How should the presence of
indent_style|indent_sizeandend_of_linefromEditorConfigaffect the comparable config values? The EditorConfig spec relies on walking the directory tree to get the values. - Should
pkg-format-indentandpkg-format-eolbe applied topackage-lock.jsonas well?
References
- This should cover the use cases mentioned in [RRFC] Don't expand tabs by default #420
- Prior art: fixpack
- This RFC covers only the configs necessary to format a
package.jsonfile.fixpackalso will warn/error on missing top level keys, which is not covered by this RFC.
- This RFC covers only the configs necessary to format a
Activity
isaacs commentedon Aug 4, 2021
Any reason why this is specific to
pkgand not justjson? It seems surprising thatpackage-lock.jsonwould use a different setting thanpackage.json, or the output fromnpm <cmd> --json.Some other prior art (the module we use to organize package-lock.json): https://github.com/isaacs/json-stringify-nice
Note that changes to the defaults, if it causes churn in the git history, will be cause for much user outrage!
lukekarrys commentedon Aug 11, 2021
I see value in
eolandindentsettings applying to alljsonoutput, and the rest I think make sense aspkgonly. I think if that's the case, it makes sense to split the naming of the settings topkg-format-*andjson-format-*.lukekarrys commentedon Aug 18, 2021
Yes, the goal is to have no churn in git history when running any commands unless config values have been changed. For
eolandindentspecifically I think the following should work in a minor version:package.jsonpackage.jsonexists (egnpm init) and no config item exists, try.editorconfig'\n'and2)dgchrt commentedon Aug 18, 2021
Changes to defaults should cause no churn, because they will not affect old files, only new files. Or do you see it differently?
ljharb commentedon Aug 18, 2021
@diogoeichert defaults include "editing package.json when you run
npm install", so it would definitely affect old files.dgchrt commentedon Aug 18, 2021
Oh, I see. I think @lukekarrys' proposal would prevent that, though:
isaacs commentedon Aug 18, 2021
Summarizing discussion:
npm pkg formatwill rewrite the file based on the configs it loads.Getting the configs:
npm.config.find('eol') !== 'defaults'), use that..editorconfigif it exists.\nand2.isaacs commentedon Aug 18, 2021
npm pkg format-validateornpm pkg format --dry-runor something to check whether it would be changed bynpm pkg formatljharb commentedon Aug 18, 2021
For "would be changed", the critical part is that it exits 0 when no changes, and exits nonzero when changes.
lukekarrys commentedon Sep 1, 2021
This is now being tracked in npm/statusboard#384.