vim, git, aws and other three-letter words

Software Development Notes

Installing npm packages from GitHub

Sometimes it is simpler to keep the package on GitHub, for example, if you have a fork of a published package with some private changes. So you can avoid cluttering the npm registry with similar packages, creating confusion for other people.

npm supports installing dependencies from GitHub, but it is also good to have versioning for your package, so you can use it exactly like other packages, develop it independently and upgrade the dependency for the main project in a controlled way.

Preparation

Add a build branch to keep the last published version of the package: 

git checkout -b build
git push -u origin HEAD

The build branch can include some files that are normally excluded from git control, for example, results of the webpack build.

Workflow

The workflow I use is this:

  • Make the changes as usual, create branches / pull requests, merge them to master
  • Prepare a release:
    • Check out the build branch: git checkout build
    • Merge master into it: git merge master
    • Run commands to generate the build (if any), like npm run build
    • Add build files to git: git add buiid/. and git commit -m "Rebuild"
  • Push changes: git push origin HEAD
  • Tag the new release: git tag 3.1.1 -a; the -a flag means an annotated tag, so git will also ask for a description
    • Add the list of changes to the annotation (I mostly use titles of pull requests along with the PR id, like "Fix search, #19"; the PR id will turn into a link in the GitHub UI)
  • Push the tags: git push origin --tags

Note: don't forget about semver: increase the last number for fixes, the second for new features and the first for breaking changes.

Now, the new release will appear on GitHub under "Releases", for example, https://github.com/serebrov/emoji-mart-vue/releases.

Use the Package

Include the package from GitHub in package.json: 

"dependencies": {
  "emoji-mart-vue": "github:serebrov/emoji-mart-vue#3.1.1"
}

Note that we specify the tag (#3.1.1 in the example above), so we can work on the package and release new versions (create new tags) and update the package version used by the main project when we want / need that.

Tags: npm