Re-publishing gimme_readme to npm with GitHub Actions

This week in my Open Source class, my classmates and I were tasked with publishing each of our own programs to a package registry.

When you hear someone say code registry, package registry, or registry, I like to think of these words as representing a place where developers and companies publish their code for others to download. For a more accurate description, you can read this article by Mozilla:

Why download code from a registry? Why not just go to GitHub?

Individuals familiar with GitHub might wonder, "Why should I even bother posting my tool to a registry? Why not have my users go to GitHub, clone my repository, install the necessary dependencies, build the intermediary files, and run my program?".

Long story short: developers publish their code to registries to make it easy for end users to use their programs.

With that little introduction on why we publish code to registries, let me tell you my process of publishing my JavaScript tool, gimme_readme to the npm registry which was built to host JavaScript code.

You can download my code by visiting its npm registry link below:

Re-publishing my code to npm

As mentioned in the title of this article, I have already published my code to npm before, and this time around, I was re-publishing my code with new features that weren't included in a previous release.

In addition to publishing the new features that my code has, I also wanted to ensure my end users systems weren't bloated with any extra files from my program.

Here is a picture that shows what my users are currently getting when they download gimme_readme, following the instructions on the `npm registry:

As you can see above, there are a lot of folders and files that are unnecessary for a user to have (as opposed to a developer). For example, do you think my users would want my "tests" folder to test my program's code? Probably not. Do you think my users need the config files needed to format and lint my source code? Probably not. Do you think my users would need to use my ".github" folder for any particular reason? Probably not.

To this end, I have been working to find a solution to minimize what is downloaded by a user; specifically, I want them to only have the source code needed for my program to run.

To .npmignore or to not .npmignore? That is the question.

As I was thinking about re-publishing my code, I was also talking with my friend Uday Rana, about the idea of using a .npmignore file to "ignore" files I didn't want to publish.

Literally right after I mentioned the topic, Uday Googled .npmignore, and found an article written by Jeff D on why one should never use a .npmignore file. To be clear, I wholeheartedly agree with Jeff's article.

Essentially, the idea is that we should be explicit with what we want to publish (whitelisting), as opposed to stating which files we don't want to publish (blacklisting).

Whitelisting the files we wish to publish is simple with npm. All we need to do is edit our package.json file by adding a "files" option, that indicates which files we want to publish for our program.

Below, I've taken a screenshot of package.json's "files" option, which states, "include the src/ directory when publishing this program". I have since committed these changes and these changes are available in my v1.0.0 release of my code.

NOTE: Certain files by default, are always published to npm, regardless of what you specify or don't specify in your "files" option. If you want to learn more about how to use the "files" option, check out npm's official documentation on how to use the file option.

After publishing my code to npm with my updated package.json, users that install/re-install gimme_readme will now have a lot less bloat on their computers! See the difference below:

Adding a GitHub action to publish my code to npm when I add a new release

Besides enhancing the experience of my users (by reducing the bloat that comes from installing gimme_readme via npm), I also added a continuous development pipeline (cd pipeline for short) that would automate my publishing process to npm when I make a new release on GitHub. For exact details on how to do this, you can refer to GitHub's Publishing Node.js packages guide. This feels good now, because at the click of a few buttons, I'm able to publish code that I know is stable (according to my CI pipeline), from GitHub.

You can find the code for my cd pipeline here.

Testing with Uday

As I mentioned earlier, I was working with my friend, Uday Rana, with regards to testing. At the time of writing, he was able to install my tool, and use it like so:

Things look good to me, and most of the options I have for my tool more or less behave the way he expects. But I'll have to repeat this process again, because I have some further optimizations I want to add!

The journey never ends... but that's what makes it fun!

I have also recently heard of ways to optimize my code further. Particularly, I'm invested in learning how to improve my CI and CD pipelines by learning about composite actions, and reusable workflows with regards to GitHub actions. My hope is that these techniques will help me reduce the amount of code I write, and offer some type of performance boost! I don't know much about these topics yet, but you can bet I will probably blog about it soon.

And that my friends, concludes what I wanted to talk about in this blog.

See you next time!