So your NPM module is broken. Time to find a different one right? WRONG!

So you are working on your brand new app that is going the change the world. All you know is JavaScript, but this world changing app is so cool that it’s too cool for the web, so you decide to make it an electron powered desktop application. What is electron you ask? It is a wrapper for node.js that allows you to write desktop applications in JavaScript, html, and CSS and deploy to all major desktop platforms. Neat!

You start going through the electron docs and building your application. Everything is going swimmingly. You get to a key feature of your app and realize… electron can’t do that. Not a problem. Surly you are not the first one to want this functionality. Let’s go search NPM to see if there are any packages that do what you want. Low and Behold, a module that does just what you want. Lots of downloads, recently updated, this seems legit. Gosh isn’t open source great!

So you bring the package into your project, and test it out. Everything looks good, the package is doing what it is supposed to, and you continue coding your world changing app. Hack, hack, hack … hack, hack, hack, crash.

Wait, what just happened? You were not even changing the part of the code that caused crashed. Even worse when you start your application up again it works just fine. After an hour or two of coding you realize what you are doing to trigger the crash and are able to track down the source of the problem, which leads you to a bigger problem. The code that is breaking, it’s not your code. It’s not all those lines that you wrote yourself and understand fully, it’s that awesome package that you pulled in before.

At this point I think it is human nature to think “This tool that I am using is broken. I should get a different tool”, but that’s not the only option. That super cool package that broke, the mysterious black box that you pass parameters into and it does what you want, it is not really that mysterious. It is JavaScript just like the code you have been writing, which means YOU CAN FIX IT! Whoa, what a concept.

Every package that you install with NPM is can be found in the node_modules directory in the root of your project. (Note: many text editors like atom hide files and directories that are listed in the .gitignore file from the file tree. If this is the case, you can still find the node_modules folder listed in your filesystem.) These packages can be debugged just as easily as the rest of your codebase.

The scenario outlined above may seem unlikely, but it happened on a recent project that I was working on. In that instance there was no other package to replace the one that broke, so we had to fix it.

The process for doing so looked something like this:

  1. Identify the specific function that you are importing that is causing the problem. Hopefully when your app crashes it will give you an error indicating which line caused the crash. Take a look at this code. Are there any obvious errors? Place a debugger in the top of the function and test to see if all of the local parameters are what you expect them to be. If something is not coming in the way that it is supposed to follow it to its source, and repeat the process outlined above until you trace the problem all the way back to the import/require.
  2. This step is big and could save you a lot of time. Go look at the GitHub issues that are open for this package. It is likely that you are not the first person to run across this bug, and there may be a fix outlined in the issues even if the fix has not been merged into the repository. If you do not see an issue that describes your problem, then add it to the list. Give the package author as much information as you can to work with. Include steps to recreate the problem, key information about your system, and any error messages that you saw.
  3. If there is no easy fix in the issues it is time to crack your knuckles and debug the code yourself. This is not your codebase, so it will be hard, but I have faith in you. Start by identifying the export that you are importing in your codebase and work backward from there. Look for any values that seem incorrect and keep an eye out for any lines of code that may be throwing errors. Every package is different, so I can’t give you much more guidance in the ‘Fix it’ step than this, but the principles of debugging are the same.
  4. You fixed it! Great! You found the code that was causing problems and you were able to get your app working. All done right? Actually not quite. If someone were to clone down your repo and run npm install they would inherit the same problem that you were running into earlier, because the fix you just implemented is not in the parent repository. There are two things that you could do to address this problem. One option would be to submit a pull request on the package repo that fixes and closes the issue that you created in step 2, then wait for the plugin author to merge in your fix. Note that you will want to run npm install again once the fix is merged in to pull the update into your app. Sometimes though, you do not have the time to wait for the plugin author to review your code a merge in your change (a process that can take a long time in some cases). If this is the case, you will need pull the package out of the node_modules folder and into your repository. The steps for doing so look something like this:
  • Copy the package directory in node_modules that you fixed and all of its contents into a vendors directory in your repository.
  • Remove the package dependency from your package.json
  • Run npm prune to remove the old package
  • Find all of the places in your code that you require(‘aBrokenPackage’) and change it to require(‘vendors/aBrokenPackage)

This way when someone clones down your repo they get the fixed code as part of your repository as opposed to the broken package from the dependencies.

Hopefully all of the packages that you work will be stable 100% of the time, but if you do run into a situation where a package breaks don’t see it as the open source community failing you, but an opportunity for you to contribute.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.