Why NPM and Yarn f*cking suck

Opinion piece: What we can learn about documentation and logging

I have a long history of telling people I'm the dumbest person in this industry. This comes with the con that people think I'm dumb, but also an amazing pro.

If I can read your documentation and use your tool, you did an amazing job because you got an idiot like me to use it. Extra points for a fast "aha!" moment.

NPM and yarn are f*cking shit, I hate javascript, and can someone / something please address the dumpster fire we have going on holding the entire front end of the internet together. It's 2 AM, let's chat boys and girls.

Welcome to Hacker f*cking noon, where we can write sh*t like this.

Let me paint you a picture....

I need to upload some code to the cloud, what code isn't important. The README.md for step 1 is clear as day:

Requirements yarn

Run
```make zip adapter=coinpaprika```

Simple, I need yarn, then I need to run that

make

pip install

brew install yarn

And I get an error:

curl: (22) The requested URL returned error: 403 Forbidden
> Failed to download https://yarnpkg.com/latest.tar.gz.

Hmm, not sure what that means, but no worries. I can just google this, maybe the site is down? Maybe I have weird firewall rules? The triage list of possible issues is pretty long here, and I explore a number of them. After unsuccessfully triaging, I decide just to move onto the next command. I don't really need to become an expert on the ins and outs of this package to use it for it's intended purpose right?

sudo port install yarn

After trying this I get a number of other weird issues, follow similar triage paths. So let me try something else. Let me dig even deeper trying to figure out what I'm doing wrong.

• I google the error
• Check github for issues
• Try the command on my friends computer and ask them
• Spin up a Ubuntu VM in my Google cloud and try to install using the f*cking Ubuntu commands it f*cking supplied, and then start to google and triage those errors, till finally I come across this sh*t.

You can install yarn with NPM, just run:

npm install yarn -g

I suspect this won't work, but I of course try it both on my mac and my linux VM anyway, and then proceed to lose my f*cking sh*t.

The INSTANT I saw npm I knew all hope was lost.

Which brings me to my first point.

1. Clear, concise, logging is critical

You are a coder, you work with computers. We get it, we are technical people, however the users trying to use your tools are human. When an issue comes up, a human is going to fix it. Not a robot. A human. And humans are emotional creatures.

Every second your tool is being debugged by a developer, their hate for your stupid logo grows, and want for an alternative grows.

It's a great way to drive away developers. So if you'd like your project that you've spent years building to be despised by the community and moved on from, then please, don't add logging. Here are some tips. I know it's hard and a bit tedious, but every time you get an error and someone doesn't understand the issue about why the issue happened, you have a responsibility to upgrade your error and documentation so that anyone can use it seamlessly.

Here is a great example of what I think is sh*t:

patrick@Patricks-MacBook-Pro-2: [~/code/lottery-react -  (master)] $ npm run start

> lottery-react@0.1.0 start /Users/patrick/code/lottery-react
> react-scripts start


There might be a problem with the project dependency tree.
It is likely not a bug in Create React App, but something you need to fix locally.

The react-scripts package provided by Create React App requires a dependency:

  "babel-eslint": "10.0.3"

Don't try to install it manually: your package manager does it automatically.
However, a different version of babel-eslint was detected higher up in the tree:

  /Users/patrick/code/node_modules/babel-eslint (version: 6.1.2) 

Manually installing incompatible versions is known to cause hard-to-debug issues.

If you would prefer to ignore this check, add SKIP_PREFLIGHT_CHECK=true to an .env file in your project.
That will permanently disable this message but you might encounter other issues.

To fix the dependency tree, try following the steps below in the exact order:

  1. Delete package-lock.json (not package.json!) and/or yarn.lock in your project folder.
  2. Delete node_modules in your project folder.
  3. Remove "babel-eslint" from dependencies and/or devDependencies in the package.json file in your project folder.
  4. Run npm install or yarn, depending on the package manager you use.

In most cases, this should be enough to fix the problem.
If this has not helped, there are a few other things you can try:

  5. If you used npm, install yarn (http://yarnpkg.com/) and repeat the above steps with it instead.
     This may help because npm has known issues with package hoisting which may get resolved in future versions.

  6. Check if /Users/patrick/code/node_modules/babel-eslint is outside your project directory.
     For example, you might have accidentally installed something in your home folder.

  7. Try running npm ls babel-eslint in your project folder.
     This will tell you which other package (apart from the expected react-scripts) installed babel-eslint.

If nothing else helps, add SKIP_PREFLIGHT_CHECK=true to an .env file in your project.
That would permanently disable this preflight check in case you want to proceed anyway.

P.S. We know this message is long but please read the steps above :-) We hope you find them helpful!

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! lottery-react@0.1.0 start: `react-scripts start`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the lottery-react@0.1.0 start script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/patrick/.npm/_logs/2020-05-08T04_38_46_190Z-debug.log

What the f*ck

Usually, my terminal doesn't take up the whole screen, so I only see the bottom. I can only image a new developer's reaction seeing the screaming

npm ERR!

helloWorld

The GOOD thing about this (if you don't instantly go catatonic), is that if your anxiety meds calm you down from the epileptic induced error overload, if you scroll up, it does give you some good tips that DO usually solve the issue. Which is:

You probably forgot to run npm install silly

Which I have a different issue with,

pip install

requirements.txt

Anyway, the logging has a lot of good information in it, which is awesome, and it is VERY clear, which I love. The part that is ass is the fact that it's the length of an 8th graders essay where the grading rubric was based solely on whether or not they hit 1,000 words.

The other issue is why the living hell are

node_modules

2. Documentation needs to reduce friction

If you want people to use your tool quickly and efficiently, they need to have an "aha!" moment quickly and efficiently. This is especially true for new developers, since ofter once someone finds a tool that works, they tend to stick to it.

Let's look at the documentation for pip and npm? Each home page has a "Getting started" or "Quickstart" page. Great! That's what I want! To quickstart!

Here is python/pip's:

In this first section I now know almost everything I need to know. The rest of the page is as concise and beautiful as this portion. If you even hit that

install pip

pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4

YES. THIS. EVERYTHING ABOUT THIS. ITS ALREADY THERE. I'm going to need it! Why would it NOT be installed??? What's the most important thing I need from pip? It's installing packages. What is right at the top of the documentation? How to install packages. Brilliant right?

Now we go to npm's:

You would think the most important thing is creating a new user account or paying for your account.

Ya know, since they put those at the top.

But it's not.

It's not the most important thing.

The most important thing is installing packages.

3. The ridiculous dependencies

This is the one most people quote. Since javascript doesn't have a standard library like python, people are free to write there own and import anyone else's. This has the massive pro of being open-sourced as hell, but the massive con of no consensus at all, and sometimes for you to use one package someone wrote, means you need to install 2,000 other random files. Talk about "lightweight".

Oops.

This can mean that if one package is updated, broken, removed, fixed or something, your code may no longer work, and when you go to debug it you have to go 10 dependencies deep to figure out the actual issue.

This is exactly what happened in 2016 all over the world.

Not to mention that I just praised npm for being open-sourced as hell, except in this same instance they kicked someone's package to the curb to make room for a bigger companies.

#openSourcedUnlessYoureNotABigCompany

Photo by Mohamed Nohassi on Unsplash

Summary

Look, at the end of the day, I was eventually able to work out the kinks and get my project to work. And I know if I spent more time reading through everything I probably would be a lot better at these technologies. I'm not a javascript pro by any context, and I know that a response can be "Well then why do you say they suck if you're not even a pro??".

First impressions are huge. And what I'm trying to say, is that the experience of working with these tools, especially early on, shouldn't be this frustrating. If you want developers to work with your tools, reducing the complexity and friction should be a top priority. It feels like npm has reached a point where they are saying:

"Well, the web is built on javascript, and we are the dominant package manager, so they will have to come to us. F*ck them."

(Not an actual quote)

I think this will be a massive misstep for them, as we saw Microsoft go through nearly exactly the same journey. Becoming complacent, started building shit products, and then becoming dominated by competitors who were sick of their shit.

I also don't want to say pip is perfect. Virtualenvs are the programming equivalent of "wtf" for beginners, but somehow I (being the dumbest human in the industry) was able to figure it out.

And if you don't believe me. Google "npm is bad" and read the shitstorm of posts about how bad npm is. From being a poorly managed company, more information on the joke of package dependencies, why we need to address the issue of npm, the million devrants from this site, hacknews and reddit filled with hate.

And now me too.

Let me know if you think I'm just a shitty pissant coder, brilliant documentation analyst, or something else.

I have more helpful content 99% of the time, like blockchain tutorials, python and machine learning, and fintech engineering. Follow me on Medium, Twitter, Youtube, and GitHub!