This guide describes how to create and release your (open-source) software project, want to share it with the world and want a step-by-step instruction on how to publish this thing on npm?
- Semantic Versioning overview
- Create an npm account
$ npm loginto login to your (newly created) npm account.
$ npm initto start a guided process to fill out fields like license, homepage, version etc.
- Test your package locally by running
$ npm install ../path/to/your/projectfrom some other folder. Also check your install instructions in the README file - they will be displayed alongside the npm package on https://www.npmjs.com/.
$ npm publishto publish your package.
- It may take a little bit until your package is live - then check it out on the npm homepage.
These steps were taken from this overview.
My npm update routine for my open source projects.
npm version <update_type>(see this link) where
Update types adhere to the principle of semantic versioning:
- In a version
- In a version
Update the project’s
- Add a new entry for the new version you’re about to release
- At the bottom of the
CHANGELOGupdate the link of the
unreleasedversion and create a link for your new version.
- You don’t have a CHANGELOG.md file yet? - The CHANGELOG of the styled-component library might serve as a nice template. It’s the example which I follow in my open source projects.
- Add this
CHANGELOGchange (and perhaps other changes) to the commit generated by the
npm versioncommand via
git commit --amend.
npm publishto publish the update to the npm server from your local computer.
npm part is done. Now we add a tag and release to GitHub:
git pushto push your changes to GitHub.
git push origin --tagsto push the newly created tag to the remote repository so that you can add release notes there.
Go to the Github page of the project, then to
Releaseson the right-hand side.
- There to the
Tagstab at the top. There click on the three dots
...on the right-hand side of the row with the new release tag and click on
- As title pick your new version with a
vin front, e.g.
- Click on
Auto-generate release notesor add the created
CHANGELOGentry as release notes plus anything else you want to say.
- There to the
Note: In step 1 you can run
npm version patch -m "Upgrade to %s for reasons" to update with a message.
- Go to https://badge.fury.io/ and create your npm badge.
- Copy the Markdown version of the generated badge and add it to your README.md file.
Example in case the package is called
package.json file you’ll encounter versions with
^. This is what it means:
Depending on whether you prepend
^ or nothing to the version
2.0.3 the following
jQuery (it’s just an example) package version will be installed when you run
npm install or
yarn in each case:
"jQuery": "~2.0.3",: Most recent
jQueryversion up to patch release will be installed (i.e.
"jQuery": "^2.0.3",: Most recent
jQueryversion up to minor release will be installed (i.e.
"jQuery": "2.0.3",: That particular
jQueryversion will be installed (i.e.
2.0.3and nothing else)
yarn.lock file you can check which exact version is installed.
For example here version
3.6.4 of the package
core-js-pure is installed although the
package.json file mentions
core-js-pure@^3.0.0: version "3.6.4" resolved "https://registry.yarnpkg.com/core-js-pure/-/core-js-pure-3.6.4.tgz#4bf1ba866e25814f149d4e9aaa08c36173506e3a" integrity sha512-epIhRLkXdgv32xIUFaaAry2wdxZYBi6bgM7cB136dzzXXa+dFyRLTZeLUJxnd8ShrmyVXBub63n2NHo2JAt8Cw==