59

It looks like the package will include all files (that are not ignored), even if the package.json has no "files" array.

Is that property necessary?

1
  • 3
    Somewhat related, I wanted to exclude some dirs, but include their parents. I ended up doing "files": ["dist/*", "src/*", "!/**/__tests__"],
    – Jazzy
    Apr 17, 2019 at 17:56

4 Answers 4

65

You can think of the files property in package.json as an allowlist of all files that should be included in a npm release and .npmignore as a denylist of all files that should not be included.

As a rule of thumb, for my own projects I usually use:

  • files when my project has lots of auxiliary files like build scripts, config files, etc., that do not need to be included in a npm release
  • .npmignore when there are only a few such auxiliary files

Both options are useful in different scenarios in my mind.

1
  • Will everything not in files be ignored?
    – Asker
    Jul 3 at 7:49
30

Not really, you can do everything using .npmignore because all files are added unless otherwise stated.

You can see more here

4
  • 1
    Thank you. That manual doesn't really state that all files are included by default, that's why I was wondering.
    – P Varga
    Jun 16, 2016 at 15:23
  • 27
    .npmignore blacklists files, while "files" whitelists. The latter is a much better strategy to avoid publishing unwanted files. Jan 31, 2019 at 17:52
  • 5
    Do not use .npmignore. medium.com/@jdxcode/… Mar 10, 2019 at 18:52
  • Careful. npm will typically ignore your .gitignore files. If you add a .npmignore and don't pop in your .gitignore files, you're going to end up publishing your secret keys, etc into your public npm package. Apr 13, 2021 at 19:31
18

This article makes a good argument for using the files property (a whitelist, as F Lekschas said), instead of using .npmignore. Reasons include:

  • Using .npmignore causes .gitignore to be ignored, which may be unexpected by many developers.
  • Often developers keep credentials in a package for development purposes, and they certainly don't want to include them in a production package. Using a whitelist technique greatly reduces the likelihood of accidently packaging stuff like this.

Note that some files are included even if you don't whitelist them. These include:

package.json
README
CHANGES / CHANGELOG / HISTORY
LICENSE / LICENCE
NOTICE
The file in the “main” field

Edited to address comment.

3
  • Point taken and addressed. Thanks.
    – zumafra
    Dec 5, 2018 at 16:47
  • 1
    npmignore does not causes .gitignore to be ignored, from daily work with both.
    – vsync
    Nov 1, 2020 at 17:18
  • @vsync It does in the context of npm. Adding an npmignore file makes npm stop ignoring files in gitignore. Jun 25 at 15:37
12

When there is no .npmignore file, the contents of .gitignore will be used. So be careful when adding generated directories like dist/to your .gitignore as they might end up not being in your production tarball. When that happens, you can use the "files" array in package.json to include them, as includes from that file will never be excluded.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.