Today's Javascript, from an outsider's perspective

Today I tried to help a friend who is a great computer scientist, but not a JS person use a JS module he found on Github. Since for the past 6 years my day job is doing usability research & teaching at MIT, I couldn’t help but cringe at the slog that this was. Lo and behold, a pile of unnecessary error conditions, cryptic errors, and lack of proper feedback. And I don’t feel I did a good job communicating the frustration he went through in the one hour or so until he gave up.

It went a bit like this…

Note: N_ames of packages and people have been changed to protect their identity. I’ve also omitted a few issues he faced that were too specific to the package at hand. Some of the errors are reconstructed from memory, so let me know if I got anything wrong!_

John: Hey, I want to try out this algorithm I found on Github, it says to use import functionName from packageName and then call functionName(arguments). Seems simple enough! I don’t really need a UI, so I’m gonna use Node!

Lea: Sure, Node seems appropriate for this!

John runs npm install packageName --save as recommended by the package’s README John runs node index.js

Node:

Warning: To load an ES module, set “type”: “module” in the package.json or use the .mjs extension. SyntaxError: Cannot use import statement outside a module

John: But I don’t have a package.json… Lea: Run npm init, it will generate it for you!

John runs npm init, goes through the wizard, adds type: "module" manually to the generated package.json. John runs node index.js

Node:

SyntaxError: Cannot use import statement outside a module

Oddly, the error was thrown from an internal module of the project this time. WAT?!

Lea: Ok, screw this, just run it in a browser, it’s an ES6 module and it’s just a pure JS algorithm that doesn’t use any Node APIs, it should work.

John makes a simple index.html with a <script type="module" src="index.js"> John loads index.html in a browser

Nothing in the console. Nada. Crickets. 🦗

Lea: Oh, you need to adjust your module path to import packageName. Node does special stuff to resolve based on node_modules, now you’re in a browser you need to specify an explicit path yourself.

John looks, at his filesystem, but there was no node_modules directory.

Lea: Oh, you ran npm install before you had a package.json, that’s probably it! Try it again!

John runs npm install packageName --save again

John: Oh yeah, there is a node_modules now!

John desperately looks in node_modules to find the entry point John edits his index.js accordingly, reloads index.html

Firefox:

Incorrect MIME type: text/html

Lea: Oh, you’re in file://! Dude, what are you doing these days without a localhost? Javascript is severely restricted in file:// today.

John: But why do I… ok fine, I’m going to start a localhost.

John starts localhost, visits his index.html under http://localhost:80

Firefox:

Incorrect MIME type: text/html

John: Sigh. Do I need to configure my localhost to serve JS files with a text/javascript MIME type? Lea: What? No! It knows this. Um… look at the Networks tab, I suspect it can’t find your module, so it’s returning an HTML page for the 404, then it complains because the MIME type of the error page is not text/javascript.

Looks at node_modules again, corrects path. Turns out VS Code collapses folders with only 1 subfolder, which is why we hadn’t noticed.

FWIW I do think this is a good usability improvement on VS Code’s behalf, it improves efficiency, but they need to make it more visible that this is what has happened.

Firefox:

SyntaxError: missing ) after formal parameters

Lea: What? That’s coming from the package source, it’s not your fault. I don’t understand… can we look at this line?

John clicks at line throwing the error

Lea: Oh my goodness. This is not Javascript, it’s Typescript!! With a .js extension!! John: I just wanted to run one line of code to test this algorithm… 😭😭😭

John gives up. Concludes never to touch Node, npm, or ES6 modules with a barge pole.

The End.

Note that John is a computer scientist that knows a fair bit about the Web: He had Node & npm installed, he knew what MIME types are, he could start a localhost when needed. What hope do actual novices have?