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:
What the user would really use is indeed the content of /dist/.
I've been using a starter kit with a build process that:
package.json 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?
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.
The common practice is to have a source code on npm, not the result of transpilation/minification/etc. It is also common to publish modules that don't need any transpilation in the first place.
If your module cannot be used in Node directly without transpilation (which would be very unusual for a module on npm and certainly not expected) then you either have to make sure that it is transpiled during installation (which is tricky and can corrupt user's file system if done wrong) or to include the dist in your published modules.
If you're going to include the dist in the published module then you need to make sure that the correct file is loaded when people require your module and that you always build a fresh dist before doing npm version and npm publish.
My advice, though, would be to write your Node modules in Node. That way they will be usable directly with small download, fast installation, no problems with transpilation and readable error messages - the last part is very important during debugging.
There is one serious problem with publishing transpiled code that is often overlooked. Publishing code that is different in any way than the actual source code, whether it is transpiled, minified or obfuscated in any way, has some security implications. It's very hard to audit transpilation results and you have to do that if that is the code that is actually being run (especially if you didn't transpile it yourself).