npm / npm/rfcs

[RRFC] Avoid distributing Readme.md when is not needed

Open
#744 15 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
777
Forks
267
PR merge metrics
No merged PRs in 30d

Description

Motivation ("The Why")

I found two packages that ship Readme.md, chalk and commander.js.

If we stop shipping Readme.md, we can save 631GB and 1.3TB per week of bandwidth for these two packages.

If we consider all the packages in the NPM ecosystem, I think the bandwidth that can be saved is huge.

Example

I created two PRs to propose a lighter version instead of shipping the heaviest Readme.md:

How

But I think instead of trying to fix each package, maybe we can change the behavior of NPM itself.

Current Behaviour

Today, we always include README.md.

Desired Behaviour

Not have to the README.md on the bundle.

Possible solutions

We can remove Readme.md when the repository URL is defined and if Readme.md is not included in the files.
To present the content of the NPM page, when it can be fetched from the repository URL.

Only when the user explicitly defines Readme.md in files or when the repository URL is not defined then we will keep Readme.md.

All this behavior must happen in the prepack step because we should not modify the package after it is generated, as there are many packages that send not only the .tgz but also the hash to validate the integrity, so there is no way for NPM modify package contents after publish.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing npm's prepack step, which the proposal identifies as the place for this behavior. Compare the current README inclusion behavior with the proposed repository URL and files rules; done means README.md is omitted only in the stated cases while explicit inclusion and missing repository URLs retain it.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.