An in-depth guide on how to publish your modules on , without pain. npm So, you have finished a lib, cli tool, component or some other scripts to want to share with the world.🌍 So it is time to publish it on . npm 🥇 Your first package Let’s assume, you already use for your dependencies. You installed them with or if you're super cool 😎 with npm npm install XYZ yarn If you now want to publish your package on npm there is a simple command for that: npm publish 🔥 But before we do this, we have still some points on our 📋checklist. 📦 Package.json You know that all dependencies get saved in your . Furthermore you save also relevant information about your package in this file. You can look them up package.json here However the most important would be name version description author license repository main The field defines the name your package will have in the registry and people will install your package over the name you define there. . name yarn add XYZ The tag defines the version of your package. You really should consider using . Because maybe a lot of people will use your package. And there is no worse feeling then breaking peoples production code because you introduce breaking changes but only change the patch version of your package. 🙈 version semver In the field you should add a quick and on-point description, about your package. People will read it if they search for your package on npmjs.org description npm search shows title, username, version and description defined in your package.json In the field you add your name and e-mail, so people know who published the package. It's common to add it in the form of . author Name <e-mail> I guess the field is one of the most forgotten fields. People often think it's not important. However if you want people to use your package, maybe even in bigger projects you should add a license. So they know if they can use it in commercial projects, what are the restrictions and so on. license that definitely You should also add the field, with a link to the github repo and you can also add the field with the link to the github issues page. So people can report bugs and know where to request features. repository bugs You can also add which help people to find your package if they search for something on npmjs.org keywords 🗄 Dependencies So we all know that you can add dependencies to your project. Or save them as with or devDependencies yarn add yarn add -D Now if you work on a project like an app or website, it does not make such a big difference if you add your dependencies as a dependency or devDependency. Because they get bundled into a browser build most of the time. However if you want to publish a package, a lib, a vue component etc. it important to get your dependencies right. is are required for your lib to work. So if you writing an API or a service and you’re using for example it is a dependency. Because it is needed for your code to run properly. Dependencies request are the one, which are required for the development. Like or for linting or or for testing. This is important, because if someone installs your package over the does not get installed! So if you add as a and somewhere in your code you have an this will not work. Because of the missing dependency. DevDependencies eslint xo karma ava yarn add my-awesome-lib devDependencies request devDependency import request from 'request' are mostly used if you write a plugin for something. Because it requires the user to have the dependency installed already. For example you want to write a plugin for and you use some functions of and extend them. If you would add as a dependency the user would have installed two versions of the one which he got installed already for his build process and the one which comes with your plugin. peerDependencies webpack webpack webpack webpack Which is nonsense. You would have to update your on every release of a new patch and update the dependency version. With you say, If someone would install your plugin would mostly work, too. There would be a but as long, there would be no breaking changes it would work. This way you give the user freedom to chose the version and upgrade the dependencies. package.json webpack peerDependencies Hey look, you need webpack to run my plugin, so install it please. Prefered version is 2.1.x webpack 2.2.x peerDependency version mismatch 🚪 Entry Points Now comes a fun part. The entry points of your lib/package. This one depends on the type of your package or lib. Is it a node module? Is it a browser plugin? heavily The basic entry point will be defined over the field. There you can add your for example . If you transpile your source or bundle it, you can define the dist file there. main index.js "main": "dist/my-awesome-lib.js", And if you publishing node modules, you will be fine with this one. But if you’re going to publish something for the browser there are more fields to know. For example the field. If you publish your lib on npm it will be available over . It's a CDN so people can pull your scripts into their scripts without installing them over npm. unpkg unpkg https://unpkg.com/package@version/file In the field you can define the default file, which get served if someone includes unpkg [https://unpkg.com/package](https://unpkg.com/package.) . Most of the time, it is a good practice to define the minified version of your lib there. "unpkg": "dist/my-awesome-lib.min.js", Last but not least, there are two more fields. The and fields. Which are used by modern build systems like Webpack 2, to grab ES6 Modules. module jsnext:main So you have build your lib. Mostly with modern ES6. People want to use it directly in the browser. So you need to transpile it. But as you also have dependencies, you need to bundle the dependencies into it. So you generate an module. UMD But some people may want to use your package with browserify and gulp. Or with webpack 1. So you need a transpiled and bundled build. However we now have 2017 and things like tree-shaking are now in fashion. To do so, you need an extra build. A ES Module build. Where most of the functions and statements get transpiled into ES2015, except the import and export statements. CommonJs I think right now, only supports ES Modules as a target output. (But you can transpile with with babel,too) So if you have an ES module you can set the entry in the and / or field. Rollup module jsnext:main This way, you serve different builds, for different people and environments. ⛓ Compatibility Mostly important for node modules, you can define which minimal version of nodejs should be installed to run your module. Thats important if you’re using without transpiling it down for example. async / await "engines": { "node": ">=7.8.0" }, 🚫 Ignores and ✅ Files Okay, now we have our different bundles and builds defined and we are nearly ready to publish our package. However you may have a log of stuff in your git repository. The source, maybe assets, the bundled files etc. It’s not smart to include all of this into your npm package. It’s a good practice to keep the size small. First of all, you don’t want your generated files in your git repo. So you ignore them in your .gitignore You can also add a . .npmignore If you don’t create a but you have a npm will exlcude all files defined in the .npmignore .gitignore .gitignore So, we ignored for example our folder in our because we don't want it in our repo. Now we need to tell npm, that we want to include this files. dist .gitignore So we add a array in our . files package.json "files": [ "dist" ], You can also be more explicit and add only files "files": [ "dist/my-awesome-lib.js", "dist/my-awesome-lib.min.js", "dist/my-awesome-lib.esm.js" ], 💯 Publish Now we are ready to publish our package. But because we are developers, and developers are lazy we should add an additional command to our scripts. The command script. prepublish This one runs, before every . So it is good practice to for example clean your node_modules and make a fresh install of the dependencies, lint and test your code and then build your code before a publish. But thats up to you! 👇🏻 npm publish "scripts": { "prepublish": "yarn run lint && yarn run test && yarn run build" }, And finally we run . Keep in mind that you need an account on npmjs.org ;) npm publish 🏷 Dist-Tags Last topic is a very handy one! Dist-tags. If you publish your package, it will automatically get the tag for the version you published it. @latest People can install your package with a strict version or the latest tag: or which is equivalent to yarn add my-awesome-package@0.0.1 yarn add my-awesome-package my-awesome-package@latest Now there are some circumstances where you will need dist-tags. One is if you support multiple versions of you package. Good examples are webpack, vue and many more. Where you start with a v1 but then working on a v2. Let’s say your package is at v1.10.0 but you’re working on a v2.0.0 release and want people to test it and report issues etc. The problem is, that if you simply it, it will get the latest tag. So everyone installing it over will get the unstable v2.0.0 which is not what we want. For this purpose we have tags. You can list your tags with and you will get a list of tags and package versions assigned to them. npm publish npm install my-lib npm dist-tag ls So you can add a tag to your publish command now. npm publish --tag beta This way the current version v2.0.0 will be tagged with beta. And the tag remains on the v1.10.0 @latest Now you can install it over npm install my-awesome-lib@beta -D 🔥 It’s important to know that you can only assign one version to a tag. And you can’t overwrite changes to a version. This is quite important for testing purpose. I learned myself the hard way, that only because your code is working locally and the unit tests pass, this does not mean that the bundled file published on npm will work like you think. Thats why it’s good to test your packages before releasing with the tag. You can use the good old release candidates for this. Because if you change the version of your package from 2.0.0 to 2.0.1 and publish it with the tag, and then you see that you still got a bug into it, you need to publish the next one with 2.0.2. You can't make a change to the 2.0.1 release and publish it with the same version with the latest tag. @latest beta Thats why or postfixes come handy. release candidates beta You simple set the version in your to 2.0.0-rc1 and publish it with the beta tag. Then you can test it and only bump the rc1 to rc2 etc. If you think you ready to go, you publish it as 2.0.0 ⭐ package.json
