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.
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:
```make zip adapter=coinpaprika```
Simple, I need yarn, then I need to run that
command. Now, I have worked a lot with python, and maybe I'm spoiled because
works 99% of the time, but this can't be much worse right? I have a macOs, how do I install on this OS? Let me go to their documentation page
. It seems so straightforward! This is great! I can run one of multiple commands, let me just try the easiest.
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?
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
> firstname.lastname@example.org 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:
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! email@example.com start: `react-scripts start`
npm ERR! Exit status 1
npm ERR! Failed at the firstname.lastname@example.org 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
at you 50 times. Giving them flashbacks of father beating down the door in his drunken stupor at 2 AM, just for trying to get
to actually print "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,
seem 1000% times simpler... Am I wrong? Please let me know. A rant for another day....
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
such a massive file? Am I just a python brat? And a java brat? And a go brat? Why is it that I don't have this massive folder on any other language. Ug, that's a rant for another day.
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!
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
link, you reach a page where the first line says:
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?
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 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.
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.
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:
(Not an actual quote)
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 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
, and GitHub
Subscribe to get your daily round-up of top tech stories!