[BUG] "files" and root ".npmignore" don't work as expected.

[dzearing]

Is there an existing issue for this?

• I have searched the existing issues

This issue exists in the latest npm version

• I am using the latest npm

Current Behavior

This seems related to npm/npm#11669 which was closed a while ago with no action. Could we re-evaluate .npmignore behavior? It is confusing, and either the wiki is wrong or there is a bug.

1. if files in package.json specifies "lib", lib content is included in the published pack
2. if .npmignore says to ignore "lib/**/*.test.*, they still are included. (unexpected)
3. even if .npmignore is added to the files list, it's still including the test files

The only way we've found to easily exclude test code from the lib folder is to include the .npmignore file in a subfolder (lib), rather then at root. Apparently that has precedence over the files list and works as expected. If we want it located at the root with all the other config files, we have to have a hacky copy step run pre-publishing.

Expected Behavior

At minimum, I expected .npmignore at root to pick off the matches resulting from the the files allow list. It does not. There's a wiki reference here which states:

You can use ignore files, optionally in combination with a files array, in order to get more fine-tuned control over what gets included or excluded.

But that only seems to be true with nested non-root .npmignore files. So that's a bug, or the wiki is wrong.

But taking a step back, one way to improve the design to be more obvious while being backwards compatible:

• deprecate .npmignore. (backwards compatible)
• files can continue being an allow-list array (backwards compatible)
• files can also be an object with explicit include and exclude arrays

"files": {
    "include":  [ "lib" ],
    "exclude": [ "*.test.*"]
}

(and include would have precedence over exclude.)

This makes things far more obvious, you don't have to muck with .npmignore being yet another config file that needs to live in a specific place, everything is contained in one package.json definition, tooling can recommend this usage, package lint tooling could even auto fix it.

The default behavior here is also desirable - having an allow list really should be the default recommended thing devs use to define what gets published. What we see in practice with .npmignore usage only is that over time tools are added without adding ignore exclusions, and things like config, logfiles, cache folders and unused build artifacts show up in the package undetected. So consumers end up downloading these things which at best ends up taking more disk space and network traffic, and at worst confuses their tooling (e.g. Typescript ends up parsing accidentally distributed source, which references dev dependencies that don't exist.)

Steps To Reproduce

1. Create project with lib folder containing foo.js and foo.test.js
2. Edit package.json to have a files list containing lib
3. Edit .npmignore to have lib/**/*.test.* exclusion
4. Run npm pack --dry-run

Expected: no test file in list
Resulted: test file in list

Environment

• npm: 9.x
• Node.js: 18
• OS Name: Windows 11

[ljharb]

files and npmignore can't be combined; if you want to use files, you'd need to use an inverse glob to exclude the test files.

Namely, files would be ['lib', '!lib/**/*.test.*']. Or, npmignore would have everything you wanted excluded, and you'd have no files property at all.

[meduzen]

files and npmignore can't be combined; if you want to use files, you'd need to use an inverse glob to exclude the test files.

Namely, files would be ['lib', '!lib/**/*.test.*']. Or, npmignore would have everything you wanted excluded, and you'd have no files property at all.

Thanks, indeed it works, thou the documentation doesn’t state that the .npmignore file is ignored when files exists in package.json. (See npm publish - Files included in package and Developers - Keeping files out of your Package.)

However, the behaviour @dzearing mentions with .npmignore working if it is placed in a subdirectory is indeed documented:

You can also provide a .npmignore file in the root of your package or in subdirectories, which will keep files from being included. At the root of your package it will not override the "files" field, but in subdirectories it will.

I think the documentation isn’t explicit enough: it’s clear that files is a way to define files included in a package (such as a whitelist) but it’s not clear it can also be used to exclude files. The reverse of this situation is that for .npmignore it’s clearly documented that you can use a negation (!) to force the inclusion of files.

Anyway, I came here for the exact same use case (excluding test files from published files) and ways of improvements for this situation would be:

• allow .npmignore to take precedence no matter where it is placed
• clarify the documentation

(Tried with latest: 10.5.2.)

[aovchinn]

if you want to use files, you'd need to use an inverse glob to exclude the test files.

but some other doc says to not do that
https://github.com/npm/cli/wiki/Files-&-Ignores#:~:text=%22The%20consequences%20are%20undefined%22

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

and docs on npm https://docs.npmjs.com/cli/v8/configuring-npm/package-json#files
do not mention negation in files property at all