Should I publish my module's source code on npm?

Question

I hope this question won't be too opinionated, I'm asking about the best/common practice for this.

I'm publishing an npm module written in ES6 and transpiled to ES5 and UMD using babel and rollup.

The file structure could be summarized like this:

/coverage/ /dist/ /node_modules/ /src/ /test/ /tools/ .editorconfig .eslintrc .gitattributes .gitignore .travis.yml CHANGELOG.md CONTRIBUTING.md LICENSE.txt package.json README.md 

The source code is within /src/ and the compiled code in /dist/.
These dirs are .gitignored:

• coverage
• dist
• node_modules

What the user would really use is indeed the content of /dist/.

I've been using a starter kit with a build process that:

1. takes the original package.json
2. removes all the scripts and dev related fields from it
3. copies it into dist
4. also copies the files LICENSE and README into dist (untouched)

The entire package source will be published on GitHub but I'm not sure about what to publish on npm:

A) the entire file structure (removing /coverage/ and /node_modules/) with a top level package.json that has an entry point to the relevant file in dist

or

B) just publish the content of dist with a stripped down package.json and the README & LICENSE. I know that just publishing the content of /dist would render source maps useless.

What is the common practice here?

Answer 1

In my opinion, the best practice is to publish both minified code in dist folder and also the source code in src folder. One should also include other files such as package.json, package-lock.json, README.md, LICENSE.txt, CONTRIBUTING.md, etc which are at the root package directory.

To achieve this, one should use files property in package.json to whitelist what needs to be published to npm instead of finding what is not required to be published by blacklisting in .npmignore.

The dist folder should have only minified bundle and no need to generate another package.json in dist folder by removing scripts, devDependencies, etc.

This is because when consumer of package do npm install <package name>, it installs only the packages inside dependencies and ignores packages under devDependecies.

The minified files can be used by browser by referring directly from scripts tag where load time will be smaller due to small file size while modern frameworks such as angular will use un-minified code. Modern frameworks have their own build tools, like webpack/rollup which create a minified bundle-file.

There is no need to have a top level package.json that has an entry point in the main field to the relevant file in dist. Instead, in my opinion, the top level package.json should have entry point to relevant file such as index.js at the same root package level.

Finally, one can run npm pack to see what is inside the tarball and then finally do npm publish to npm registry for public use from inside root package folder.