[DOCS] Wiki: Files & Ignores -> better hint how to exclude from files

[benjie]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Enhancement, not another kind of Docs Enhancement.

• This is a CLI Docs Enhancement.

Description of Problem

https://github.com/npm/cli/wiki/Files-&-Ignores

"Files" states:

"The consequences are undefined" if you try to negate any of the files entries (that is, "!foo.js"). Please don't. Use .npmignore.

To the casual observer this may seem to imply that you should stop using files and instead use only .npmignore, however as commented by @iarna in npm/npm#11669 (comment):

Also: .npmignore/.gitignore in subdirectories DO override the top level files.

So we can solve some of this by e.g. putting a .npmignore into src/ or lib/ or dist/ or wherever.

Potential Solution

Change the text to:

"The consequences are undefined" if you try to negate any of the files entries (that is, "!foo.js"). Please don't. Use .npmignore - note that you can add an .npmignore to a subfolder and it will override the files list.

Further, in the "Known issues" section, the first bullet could be changed from:

#11669 - .npmignore entries should trump entries in the files array

to:

#11669 - .npmignore entries should trump entries in the files array, but currently this only happens for .npmignore files in subdirectories

Docs URL

https://github.com/npm/cli/wiki/Files-&-Ignores

[benjie]

(Thanks for npm and all y'all do ❤️)

[lukekarrys]

I know npm-packlist has also changed since that wiki was written. Looking at the wiki page, it seems like this is a good candidate for an actual docs page which would help keep it up to date. I think generally we should use wiki pages more for CLI internals documentation (release process, how to write tests for it, etc).

[MdNomanUddin]

hey, I am new and would like to help can anyone guide how and what to do?

[RudrakshNanavaty]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Enhancement, not another kind of Docs Enhancement.

• This is a CLI Docs Enhancement.

Description of Problem

https://github.com/npm/cli/wiki/Files-&-Ignores

"Files" states:

"The consequences are undefined" if you try to negate any of the files entries (that is, "!foo.js"). Please don't. Use .npmignore.

To the casual observer this may seem to imply that you should stop using files and instead use only .npmignore, however as commented by @iarna in npm/npm#11669 (comment):

Also: .npmignore/.gitignore in subdirectories DO override the top level files.

So we can solve some of this by e.g. putting a .npmignore into src/ or lib/ or dist/ or wherever.

Potential Solution

Change the text to:

"The consequences are undefined" if you try to negate any of the files entries (that is, "!foo.js"). Please don't. Use .npmignore - note that you can add an .npmignore to a subfolder and it will override the files list.

Further, in the "Known issues" section, the first bullet could be changed from:

#11669 - .npmignore entries should trump entries in the files array

to:

#11669 - .npmignore entries should trump entries in the files array, but currently this only happens for .npmignore files in subdirectories

Docs URL

https://github.com/npm/cli/wiki/Files-&-Ignores

I would like to volunteer making the suggested changes, but I am new so I don't know where to update the docs. can anyone point out what I need to do?

[iarna]

I would like to volunteer making the suggested changes, but I am new so I don't know where to update the docs. can anyone point out what I need to do?

Seems like they locked down edit access on the wiki at some point, so I'd guess it has to be made by a npm team member.

Those docs are more dev note than end user doc. End user docs should probably be on docs.npmjs.com.

[benjie]

Agreed, but would still be good to get the facts corrected for those of us using Google 👍

[Sourav-Kumar-Panda]

Can i work on this ?

[reggi]

I was messing around with some tests in test/lib/commands/publish.js (i didn't merge this in) and could see that files in package.js always supersedes .npmignore and .gitignore, it acts as the opposite an allow-list of the files to include.

t.test('files', async t => {
  const { joinedOutput, npm, logs } = await loadMockNpm(t, {
    config: {
      json: true,
      ...auth,
    },
    prefixDir: {
      'package.json': JSON.stringify({ ...pkgJson, files: ['open/dove.js', 'bar.js'] }, null, 2),
      'foo.js': "console.log('meow')",
      'bar.js': "console.log('meow')",
      open: {
        'dove.js': "console.log('coo')",
        '.npmignore': 'dove.js',
      },
      '.npmignore': 'bar.js',
    },
  })
  const registry = new MockRegistry({
    tap: t,
    registry: npm.config.get('registry'),
    authorization: token,
  })
  registry.nock.put(`/${pkg}`).reply(200, {})
  await npm.exec('publish', [])
  t.matchSnapshot(logs.notice)
  t.equal(joinedOutput().includes('"path": "open/dove.js"'), true)
  t.equal(joinedOutput().includes('"path": "bar.js"'), true)
  t.matchSnapshot(joinedOutput(), 'new package json')
})

As people have mentioned here the wiki is out of date and not really maintained anymore. I think this section of the pacakge.json docs detail files enough https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files.

Closing for now feel free to add a PR to that page here: https://github.com/npm/cli/edit/latest/docs/lib/content/configuring-npm/package-json.md