Things I’ve learned when writing my first book about advanced JavaScript
I’ve just finished writing my first book (yay!). It was one of these totally insane ideas born inside the head of not-that-well-known web developer. It will sound even more insane if I tell you what was the reason behind this ”fun activity”: a desire to create my own jQuery clone, BEMQuery. The book will be released in July by Helion (sorry, in Polish only!), but I’ve already learned a lot and want to share this new knowledge with you.
It’s not so easy to reinvent the wheel
I mean: look at jQuery. There is absolutely everything in it. Animations, Ajax, DOM manipulation… You just plug it inside your website and you’re done. What’s more, the whole library is created around the idea of a CSS selector engine (Sizzle in case of jQuery). My task was very difficult: create something as simple as jQuery and (at the same time) better in some aspects.
After diving into jQuery’s code, I found its weak point: modularization! Yes, I know that there is a way to build a subset of jQuery, but it’s still not the modularization we want today, in the era of ES6+. That’s why I’ve decided to split my library into small modules that could be used totally independent of each other (totally not inspired by CKEditor 5’s design). Since I used ES6 modules, I also had to write the whole code using the new and shiny JS version.
The second big change is (of course) the selector engine. I’m not using CSS selectors, but BEM ones — a new format I’ve invented. Quick example: block element:modifier is an equivalent to .block__element_modifier in CSS. A simple idea, but I like it.
Did I reinvent the wheel? Probably so, but my wheel is rounder.
Writing books in LibreOffice is a nightmare
Not because LibreOffice is just a “worse MS Word”. No. There are many other issues, for example incompatibility between different versions of LibreOffice and open hostility between MS Word and LibreOffice Writer. Trying to create a document that will work in these two editing environments is just a straight path to a stinking pit full of the damned in the middle of hell.
Next time I’m going to use HTML. Or Markdown. Or even LaTeX. But never LibreOffice. Totally not worth the nerves.
You can write a book in 5 days (OK, 90% of it) along with creating the code you’re describing in it
Yes, IT IS possible to write 260 pages and create the accompanying code at the same time. However some of the outcomes include ending up with a library which has an astonishing amount of 10 methods and falling asleep in the most inappropriate moments and places for the following 3 weeks.
I’ve also learned that trying to describe some very basic concepts like modules or Promise could take many pages and many hours. Just because describing modules needs the whole reasoning about why monolithic codes (like jQuery) are worse than modular ones (like BEMQuery), why we should use ES6 modules and then transpile them into UMD format etc.
So even if 260 pages for describing just 10 methods sounds very funny, it wasn’t so funny while writing it. It was simply a hard job.
Generators are great, but…
Generators are great, it goes without saying. But… try to explain them in a book — especially when they’re going to be used only in one super simple case!
It’s still much simpler to explain iterators created using plain objects than using “these fancy new generators”.
There is no minifier for ES6
Yes, there isn’t anything sensible (except some experiment). Even Uglify.js has big problems with ES6 and Google Closure Compile can minify ES6 only after transpiling it into ES5.
This is why I had to resign from writing an entire chapter about optimizing delivery of JS code to the browsers.
Node.js is released too often
When I started writing the book, the latest version of Node.js was 4.4. When I finished, Node.js 6.2 was out. Ouch.
Of course I had to rewrite the whole chapter about ES6 support in Node.js!
It’s not funny, Node.js developers!
npm packages </3
We all know well the JavaScript fatigue and it’s not just a fancy buzzword — it’s a real thing. The best example? My BEMQuery’s boilerplate has 30 modules responsible for the most basic things. 15 of them are used to create super simple tests. 8 of them are used to just bundle BEMQuery into one file in UMD format.
Don’t get me wrong: hypermodularization is a very good thing, but at the same time it’s just a pain in the neck. I decided to use karma to run my tests and just because of that I was forced to include plugins even for running tests in particular browsers. Yep, the tool that’s created to run tests in browsers uses a plugin to… run tests in browsers. The same with rollup.js, the super simple bundler: plugins for everything. It’s not wrong, it’s just tiring.
Is it the issue with the modules themselves? Not really. It’s rather an issue with the idea of how these modules should be used inside JS applications. The case of left-pad shown that hypermodularization works when the community behaves responsibly. I have the feeling that we’re trying to modularize too much. At the same time I also have the feeling that some things could be modularized more. I believe that somewhere there lays a thin border of sane modularization. I hope that we still hadn’t crossed it.
BTW did I mention that installing these 30 modules fetches around 500 dependencies?
npm version <3
I had no idea that npm has such a brilliant feature just to simplify publishing new semver compatible versions of our packages. All you have to do is to type npm version major/minor/patch inside console and press Enter. Then npm will bump the version of your package inside package.json file and prepare Git tags for it. PURE AWESOMENESS!
npm scripts > Grunt/gulp?
I’ve also experimented with ditching Grunt/gulp in favor of old, plain npm scripts. It works, but it can be really tiring and after a while the pollution in our package.json file could be much bigger than we anticipated.
For small projects (well, BEMQuery is a small project so far) npm scripts are better than Grunt/gulp (no boilerplate, no tool-dependent plugins etc.), but for bigger projects their super simplicity could be a big issue (we just need some boilerplate in such large code!).
GH Pages = documentation
My project includes one more experiment: documentation published as GitHub Pages and generated by super simple npm script.
Documentation built and published by one simple command? Maybe it’s not amazing, but I hope it serves its purpose well.
There is Alt+PrtSc shortcut
If you’re as nerdy as I am, you probably haven’t noticed that you don’t have to use Gimp to cut off the only window you’re interested in from the print screen of your Ultra HD 3 monitors’ desktop. You can simply use Alt+PrtSc!
Yes, I know…
That’s all I’ve learned when writing my book. I hope these tips will be of some use to you!
