Add comments to your npm scripts

Elijah Manor
InstructorElijah Manor

Share this video with your friends

Send Tweet
Published 6 years ago
Updated 3 years ago

The need for comments in your package.json file becomes desirable the more and more npm scripts you start to define. At first glance this might seem like a show stopper since JSON does not support comments, but there are ways around this limitation that we will discuss.

[00:01] The more and more scripts you have, there can become the need for documentation. However, since the package.JSON file is JSON, that's somewhat limiting.

[00:08] However, there are a couple techniques you can use to make it work. One is to use a double slash as your key, which lets you put whatever you want as a description and npm will ignore it.

[00:18] In this case, we'll say run, build, and serve. Then, we can come down to our test and do the same thing. Run our Mocha unit tests, and then, we'll also do it for our linting.

[00:37] Lint, our JavaScript, and Sass. Now, the downside of using the slash slash technique is that when you npm run, and we'll pipe it through Less, it'll only print out the last comment, since they share the same key, which is slash slash.

[00:52] You see it has lint or JavaScript in Sass, but all the other comments are gone. The main benefit of the slash slash technique is to document your actual package.JSON file itself and not the output when you run npm run from the command line. Another technique we could use is to start our script with a shell comment.

[01:10] Then here, we'll put an emoji, because it's fun, and then, we'll say run, build, and serve. Then, we'll separate it with a new line and a tab character.

[01:19] Now, let's quickly make the changes for our other scripts. We'll have a comment, and a zap, and then, we'll say run our Mocha unit tests, separated by a new line and a tab character.

[01:32] We'll save that and come over to our linting. Start with a comment and then have a traffic emoji, and say lint our JavaScript in Sass, separated by a new line and a tab character.

[01:46] Now when we run npm run again, piped through Less, we'll see a description of our script and the script itself. You'll notice that it's nicely indented.

[01:55] A con of the second technique I showed you is that it clutters up your package.JSON file and obscures your actual script. Outside of providing your scripts elsewhere, these are your primary options for providing comments inside your package.JSON file.

Philip
Philip
~ 5 years ago

Hey, Elijah. Adding the emoji is pretty cool. What package are using?

Elijah Manor
Elijah Manorinstructor
~ 4 years ago

Hey, Elijah. Adding the emoji is pretty cool. What package are using?

If you are using a Mac you could use ctrl-cmd-space to pull up an emoji picker OR there is a fun app for Mac that you can use http://matthewpalmer.net/rocket/

If you are on a PC you could try the Emoji extension for VSCode https://marketplace.visualstudio.com/items?itemName=Perkovec.emoji

If you have the Windows 10 Fall Creators Update, you should be able to launch the emoji keyboard within Windows 10 by either use the WIN + . (the period punctuation mark) key, or else the WIN + ; (semi-colon) key. Either should open the new emoji keyboard.