117

What exactly should I put in .npmignore?

Tests? Stuff like .travis.yml, .jshintrc? Anything that isn't needed when running the module (except the readme)?

I can't find any guidance on this.

Improve this question
3
  • 4
    should ignore everything that isn't needed when someone call npm install yourlibrary, for example .travis.yml and .jshintrc Commented Aug 4, 2014 at 18:20
  • really? even a readme? is this recommended officially anywhere? Commented Aug 4, 2014 at 18:46
  • 3
    README is automatically included regardless of .npmignore or "files" (docs.npmjs.com/files/package.json#files). Commented Jan 25, 2018 at 12:40

5 Answers 5

Reset to default
97

As you probably found, NPM doesn't really state specifically what should go in there, rather they have a list of ignored-by-default files. Many people don't even use it as everything in your .gitignore is ignored in npm by default if .npmignore doesn't exist. Additionally, many files are already ignored by default regardless of settings and some files are always excluded from being ignored, as outlined in the link above.

There is not much official on what always should be there because it is basically a subset of .gitignore, but from what I gather from using node for 5-ish years, here's what I've come up with.

Note: By production I mean any time where your module is used by someone and not to develop on the module itself.

Pre-release cross-compiled sources

  • Pros: If you are using a language that cross-compiles into JavaScript, you can precompile before release and not include .coffee files in your package but keep tracking them in your git repository.

Build file leftovers

  • Pros: People using things like node-gyp might have object files that get generated during a build that never should go into the package.
  • Cons: This should always go into the .gitignore anyway. You must place these things inside here if you are using a .npmignore file already as it overrides .gitignore from npm's point of view.

Tests

  • Pros: Less baggage in your production code.
  • Cons: You cannot run tests on live environments in the slim chance there is a system-specific failure, such as an out of date version of node running that causes a test to fail.

Continuous integration settings/Meta files

  • Pros: Again, less baggage. Things such as .travis.yml are not required for using, testing, or viewing the code.

Non-readme docs and code examples

  • Pros: Less baggage. Some people exist in the school-of-thought where if you cannot express at least minimum viable functionality in your Readme, your module is too big.
  • Cons: People cannot see exhaustive documentation and code examples on their own file system. They would have to visit the repository (which also requires an internet connection).

Github-pages objects

  • Pros: You certainly don't need to litter your releases with CNAME files or placeholder index.htmls if you use your module serves double-duty as a gh-pages repository as well.

bower.json and friends

  • Pros: If you decide to build in your dependencies prior to release, you don't need the end-user to install bower then install more things with that. I would, personally, keep that stuff in the package. When I do an npm install, I should only be relying on npm and no other external sources.

Basically, you should ever use it if there is something you wish to keep out of your npm package but checked-in to your module's repo. It's not a long list of items, but npm would rather build in the functionality than having people stuck with irrelevant objects in their package.

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Isn't there a way to remove non-usable scripts from the package.json file. E.g. testing scripts? I feel a bit messy to remove everything but keep the scripts in the file...
No, there is not. You may omit them from the package.json as that's primarily for NPM anyway and if you're only running tests, you may access them via the original command to run them.
@SamT what about package quality score, is it affected by the fact I publish tests or not?
@StefanoBalzarotti This answer was written well before package quality was popular or even a thing yet, according to npm.io's package analyzer, it only checks for the existence of a test script, but remains unaffected it appears, if the test files themselves are not present. If your tests are succinct and reliable, perhaps you should include them. It's entirely up to you.
@SamT, maybe I'll give a try. my library has 100% code coverage, perfect linting, etc but I am unable to increase code quality above 67%. The problem to include tests is that I have to include also all dev packages, and the size of my library will increase of dozen of times.
80

I agree with lante's short and syntetic answer and SamT's big answer:

  • You should not include your tests in your package.
  • Your package should only contains production runtime files.
  • That will make your package more straightforward and faster to be dowloaded.

My contribution to those answers:

.npmignore is the blacklist way to achieve package file selection. But in a more practical way, you can whitelist files you need to include in your package using the files field in your package.json:

{
  "files": [
    "lib/",
    "index.js"
  ]
}

I think that's simpler, future proof and have better semantics ;)

Improve this answer

10 Comments

... to say nothing of easier to remember and less accident-prone to use (if you're as forgetful as I can be). Thanks for the tip, this is great.
I like this approach.
I think you can even omit the "index.js" assuming it is the 'main' file in your package.json :)
Ignoring images and unnecessary documents is fine. But ignoring the tests is probably not a good idea. Downloading some extra KB's doesn't take that much time and doing a recursive npm test across all node_modules can give you a hint if something works different in a certain environment.
@NicolásFantone The files property accept glob pattern as well. So we can ignore the test files without creating .npmignore. files: ["lib", "!lib/**/*.test.js"]. :)
|
16

Just to clarify, anytime someone do npm install your-library, npm will download all source files that the package includes. Those files that were included in the .npmignore file in the source code of the package your-library will be excluded when publishing the lib, so users of your-library won't download them.

Know that people installing your library will need just your library running, anything else will be not necessary.

For example, when someone installs a library, its probably that he/she doesn't care about your .travis.yml or your .jshintrc files, or even some images, Grunt files, documentation, etc.

.npmignore could let your npm package to have less files, and faster to be downloaded

Improve this answer

1 Comment

The sentiment here is good, but to clarify: .npmignore doesn't directly affect what's downloaded, it affects what goes into your package when you npm publish and upload. This indirectly does create smaller files to download.
4

Don't include your tests. Oftentimes tests are like 5x the size of the actual codebase. As long as your tests are on Github, etc, that's good enough.

But what you absolutely should do is test your NPM package in its published format. Create some smoke tests that reside in the actual codebase, but are not part of the test suite.

You can read about testing your package after tarballing it, here: https://github.com/ORESoftware/r2g

How to test an `npm publish` result, without actually publishing to NPM?

Improve this answer

Comments

2

If you want your package to score high on quality on npmjs.com, you should include everything that npm thinks is important:

Quality includes considerations such as the presence of a README file, stability, tests, up-to-date dependencies, custom website, and code complexity. (Source)

So you want to include your README to the package. And after some experimenting: including the tests (and with these the sources) also increases your quality score.

Improve this answer

Comments

Your Answer

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

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.