Why does 'yarn install' rewrite package.json?

[rdicroce]

Like the title says: 'yarn install' causes package.json to be rewritten even though there's no reason Yarn needs to modify the file. I'm not sure if this is a bug, per se, but it's definitely surprising behavior. I wouldn't care, except that when Yarn writes package.json, it also sorts dependencies/peerDependencies/etc. So the file content after an install is semantically equivalent, but the raw bytes might be different.

As to why this is bothering me: I'm primarily a Java developer, and I'm accustomed to directly editing the package descriptor (pom.xml for Maven). I'm also accustomed to being able to group related dependencies together (in terms of how they're ordered in the file) and being able to leave comments in the descriptor to explain things, like why a dependency is needed, or why it's not on the latest version. Which you can't do with package.json, and I know I'm not the only person who finds that annoying, because some Googling finds plenty of people proposing various hacky solutions. There was even an issue about it here (#241) that was closed with no action taken because it's a complicated problem.

Well, I invented my own solution (actually the one mentioned in that issue): an automagic transformation between package.json and package.jsonc. JSON is the canonical file, and a JSONC is created from it. Comments can be added in the JSONC, and when it is saved, it gets transformed back to JSON, with the comments being parsed in a separate pass and added to the JSON as a valid JSON object. Similarly, if the JSON changes, it gets transformed to JSONC and the comments are re-inserted at the appropriate places.

It works pretty well, except for that problem of yarn rewriting the file and not preserving the ordering. I've made my magic smart enough that it still knows where the comments are supposed to go, but the re-ordering means I can't group things together.

So: should any of this be considered a bug in Yarn? IMO rewriting package.json for no reason feels like a bug. The sorting behavior also feels unintended, and ideally I'd like for Yarn to preserve the order, but I'd settle for not modifying the file unnecessarily.

[arcanis]

So: should any of this be considered a bug in Yarn? IMO rewriting package.json for no reason feels like a bug. The sorting behavior also feels unintended, and ideally I'd like for Yarn to preserve the order, but I'd settle for not modifying the file unnecessarily.

Not keeping the dependencies in alphabetical order leads to harder-to-maintain projects as you lose the ability to quickly see which dependencies are in use. That they are enforced in a consistent order is intended 🙂

[rdicroce]

Okay, thanks for that info. Would you have any interest in a patch to allow that behavior to be disabled? I don't have time to do that right now, but maybe in the future.

[arcanis]

I'd incline towards no, I'm not convinced it's a behavior that's worth the (ever so small) extra complexity.

[jeffrson]

Well, as useful as ordering dependencies can be, OTOH, yarn removes "placeholders" like "peerDependencies": {} - what could be seen as "questionable".

[martinal]

Found this now because we have an issue with yarn install rewriting package.json with formatting that differs from what biome 1.7.1 wants to use, making the tools fight back and forth.

The diff was a silly

-  "workspaces": ["packages/agents"],
+  "workspaces": [
+    "packages/agents"
+  ],

where yarn wanted the multiline version.

Took me some time to debug and I had to disable formatting package.json by biome to get around it.

IMO it's not the role of yarn install to edit files that are commited to the repository, there are tools like biome for that.

In general I would expect that doing

git checkout ...
yarn install
git status

should not show modified files.