In our team we are working with different technologies, but there are some tools we use through all our projects: git for Source Code Management and npm as a package manager for client- and server-side projects.
npm has a lot more features than most developers use. In this article we will explain some of the most commonly used functionalities in our team.
scripts is one of the most frequently used features in our team. npm can not only be used as a package manager for node.js, but is also suitable as a language agnostic task-runner.
In order to run your custom scripts with npm you just need to add some entries to the
scripts section of your package.json file:
In the above example you can enter
npm test in order to run ava. In this case you might think that this approach isn't as convenient as calling the ava command directly, since this is shorter. On the other hand, you should consider that if you don't have the folder ./node_modules/.bin exported to your PATH, you will end up calling ava as ./node_modules/.bin/ava, which isn't shorter at all. Moreover you can add the
npm test command to your documentation, without worrying about future changes to your internal tool-chain.
There are some predefined script names, as for example
start. If you define a custom script
myscript you will be able to call it via:
A useful shortcut to get a list of the commands interfaced by npm scripts is:
This will print out all available scripts and the command they will execute.
By using the natively provided hooks
you can trigger certain commands on
. You can use this feature for autogenerating a changelog running the git-changelog
Combine git hooks and npm scripts
If you want to make sure that nobody in your team pushes changes to your repository that will break your tests, you could use a tool like husky
(which gives you git hooks like
npm install --save-dev husky
and add the following command to the scripts section of your package.json:
"precommit": "npm test",
This will run
every time you enter
and it will proceed committing the changes only if the script exits with a 0 exit-code
, meaning no error occurred. You can of course decide to run other scripts than
or to hook
another command instead of commit.
Colors Of Europe
Interactive Data Visualization (Zeit Online)
Are you interested in a collaboration?
We are specialized in creating custom data visualizations and web-based tools.
You can also define variables in the config section of your package.json. This can be helpful if you want be able to change the parameters of your scripts without changing the script definition.
Let's say you have a script
to start a web-server
in your /dist folder:
"start": "http-server dist -p 8000",
and you want to be able to easily change the port without worrying about touching the right parameter, you can adjust your package.json as following:
"start": "http-server $npm_package_config_folder -p $npm_package_config_port",
As you can see we are now able to use the
$npm_package_config_port variable within our command.
Managing package-lock.json or yarn.lock files
and npm 5
introduced lockfiles. These files, respectively yarn.lock and package-lock.json, are supposed to be commited to your git repository as explained on npmjs.com
It is highly recommended to commit the generated package lock to source control: this will allow anyone else in your team, your deployments, your CI/continuous integration, and anyone else who runs
npm install in your package source to get the exact same dependency tree that you were developing on.
Unfortunately this is causing a lot of trouble in the node.js
developer community as shown by the more than 1K issues
mentioning package-lock.json in the npm
We collected a couple of useful tips to handle lockfiles, but be careful as these approaches are really naive and cannot safely avoid dependency mismatch.
1. Handle as binary files
You can add these lines to a .gitattributes file located in your root folder:
git will handle them as binary files and exclude their diff from the
git diff command output for you. From now on conflicts aren't handled line-by-line and you can therefore only decide to take the last version of the file or commit your own.
2. Generate a new lockfile
If you are not sure on what to do solving a conflict, a simple approach could be to delete the conflicted version of the file and run
npm install (or
rm package-lock.json # or yarn.lock
npm install # or yarn
3. Disable package-lock.json
A much more radical solution would be to disable
the generation of package-lock.json globally
npm config set package-lock false
In order to disable the generation of the package-lock.json file for a single project you can add the following to the .npmrc file in your project's root folder:
In the future, these files will be handled by the package managers, autodetecting and merging conflicts (see this issue
and this PR
If you want to run a package just once, without installing it globally on your machine or locally in your project, you can try npx
. It is part of npm
since version 5.2.0.
Let's say we want to try the
command. Therefore we can run:
npx git-changelog -t false -a "My nice application"
This can of course be integrated in the npm scripts section for tasks that don't run that often.
Release and Tagging
In order to keep track of version numbers, we use the
npm version command. Each time we merge the develop branch into the master we run one of the following commands:
npm version patch
npm version minor
npm version major
Followed by a
git push --tags.
This will bump the version number in the package.json and create a new git tag
for the latest version number.
is therefore a useful shorthand for creating a new release of your package and keeping track of your versions at the same time. The command should be used to follow the Semantic Versioning
patch can be used as hotfix that doesn't imply breaking changes and doesn't introduce new features
minor can be used to tag versions introducing new features and minor non-breaking changes
major is used for versions that introduce breaking changes