Monthly notes 32

Summer season is heating up and here’s the monthly notes for July. Something about JavaScript, little bit of design, touch of privacy and tools of the trade.

Issue 32, 23.7.2018


Defining Component APIs in React
Collects some of the best practices for working with React. “The following is a collection of thoughts, opinions, and advice for defining component APIs that are meant to be more flexible, composable, and easier to understand. None of these are hard-and-fast rules, but they’ve helped guide the way I think about organizing and creating components.” (from Weekend reading)

The Cost Of JavaScript by Addy Osmani at Fluent 2018
Strategies to deliver JavaScript efficiently while giving users a great expericence. i.a. audit, use code-splitting, prpl-pattern. “Improving performance is a journey.” (from @walokra)

TIL: node-jsmin (port of Crockford’s JSMin) was dropped from a lot of places as modified MIT license with “The Software shall be used for Good, not Evil” is not compliant with definition of open source software which doesn’t permit any restriction on how software may be used. (from @walokra)


Introducing Jib — build Java Docker images better
“Jib, an open-source Java containerizer from Google that lets Java developers build containers using the Java tools they know. Jib is a fast and simple container image builder that handles all the steps of packaging your application into a container image. It does not require you to write a Dockerfile or have docker installed, and it is directly integrated into Maven and Gradle.”


Brutalist Web Design
TL;DR; Content is readable on ~all screens & devices. Only hyperlinks & buttons respond to clicks. Hyperlinks are underlined, buttons are buttons. Back button works. View content by scrolling. Decoration when needed and no unrelated content. Performance is a feature. (from @walokra)

Little known trick: the <script> tag in html runs the code inside, and also hides it using css display:none. But I can change that to display:block, so that I can show sample code to the reader and also run it on the page to generate diagrams. (need to test across browsers). This also applies to <style> tags, where you can also use contentEditable to create a live editable css of the page you are on. (from @ Amit Patel)

Rebass: Flexible & functional React design system, built with styled-system
Rebass is a library of highly-composable, primitive UI components for React, built with styled-system to make building consistent, responsive web apps simpler and faster.

Tools of the trade

Terminal-based web browser renders everything a modern browser can (HTML5, CSS3, JS, video, even WebGL). Use case: run the browser in a data center with fast internet, and access it over SSH from a device that has slow/limited internet. (from Weekend reading)

@EricaJoy. Meanwhile, this hack mostly works.

“petition to make “paste and match formatting” the default paste option”


Riot Games Approach to Anti-Cheat
Riot Games published an article about their anti-cheating methods – nothing really fancy or new but, in the Hacker News thread there was an interesting comment by a cheat writer:

“The current Mac game client for League Of Legends contains full debug symbols and it doesn’t have Packman (the packer described in this article), which makes it quite easy to look through the symbols. Inside you can find all of the anti-cheat-related network packets. Now, I personally expect anti-cheat to snoop around my system when I’m doing something shady like scanning its memory. However, if I was a normal user of the game, I would be a bit concerned to know that it might be sending my recently used file names, drive names, system driver names, currently running processes, processor information, system state, and even entire binary files that it automatically deems as “suspicious”, to their servers.”

@aral and maya kosoff: “X is a service that enables you to control articles presented to your wife on the websites she usually visits, in order to influence her on a subconscious level to initiate sex. The best bit? It’s “just” adtech. It’s retargeting. It’s how Google makes money.” Also suggested use cases are “get your kid a dog” or “stop drinking” which eems to open up a whole new acquaintance micromarketing concept. Makes you think how you’re influenced and by whom.

“Imgur’s fake adherence to GDPR is exactly the kind of transgression that should trigger those multi-million euro fines. There are literally HUNDREDS and HUNDREDS of shady services getting your data. Only bulk link is to ALLOW ALL, which is also default. Tons you can’t opt-out. 👎”

Something different

“The StemCAPtain replaces the stem cap, aka top cap, piece of a threadless 1″ or 1 1/8″ headset with different functional accessories. In addition to the simple and elegant analog clock, we offer a thermometer, bottle opener, picture frame, compass, GPS mount, and USB charger”

Digital Laundry: how credit card thieves use free-to-play apps to launder their ill-gotten gains

Generating documentation as code with mermaid and PlantUML

Writing documentation is always a task which isn’t much liked and especially with diagrams and flowcharts there’s the problem of which tools to use. One crafty tool is with web and desktop editors but what to use if you want to write documentation as a code and see the changes clearly in text format and maintain source-controlled diagrams? One of the tools for drawing diagrams with human readable text are mermaid and PlantUML.


“Generation of diagrams and flowcharts from text in a similar manner as markdown.”

mermaid is a simple markdown-like script language for generating charts from text via javascript. You can try it in live editor.

mermaid sequence diagram

You can write mermaid diagrams in text editor but it’s better to use some editor with plugins to preview your work. Markdown Preview Enhanced for Atom and VS Code can render mermaid and PlantUML. There’s also dedicated preview plugins for VS Code and Atom.

To preview mermaid definition in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview.

mermaid in VS Code with Markdown Preview Enhanced

To preview mermaid definition in VS Code with Mermaid Preview press Cmd-P to open Command palette and select Preview Mermaid Diagram.

mermaid in VS Code with Mermaid preview
mermaid in VS Code with Mermaid preview

Generating PNG images from mermaid definitions

To use mermaid diagrams it’s useful to export them to PNGs. You can use mermaid.cli tool which takes a mermaid definition file as input and generates svg/png/pdf file as output.

Install mermaid.cli locally:

npm install mermaid.cli

Generate PNG:

./node_modules/.bin/mmdc -i input.mmd -o output.png

If you have plenty of defition files you can use the following script to generate PNGs:

#!/usr/bin/env bash
for mmd in ./docs/*.mmd
    echo "Generating $mmd"
    ./node_modules/.bin/mmdc -i $mmd -o ${filename%%.*}.png

Alternatively you can use node_modules/mermaid/bin/mermaid.js $mmd where mmd is the mermaid file.

PlantUML diagrams

PlantUML is used to draw UML diagrams, using a simple and human readable text description.

PlantUML is used to draw UML diagrams, using a simple and human readable text description. Diagrams are defined using a simple and intuitive language (pdf) and images can be generated in PNG, in SVG or in LaTeX format.

You can use PlantUML to write e.g. sequence diagrams, usecase diagrams, class diagrams, component diagrams, state diagrams and deployment diagrams.

PlantUML example diagram:

PlantUML diagram

Simple way to create and view PlantUML diagrams is to use Visual Studio Code and Markdown Preview Enhanced plugin which renders both PlantUML and mermaid diagrams. Alternative option is to use plantuml plugin.

To preview PlantUML diagram in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview.

PlantUML in VS Code with Markdown Preview Enhanced

There’s an online demo server which you can use to view PlantUML diagrams. The whole diagram is compressed into the URL itself and diagram data is stored in PNG metadata, so you can fetch it even from a downloaded image. For example this link opens the PlantUML Server with a simple Authentication activity diagram.

Running PlantUML server locally

Although you can render PlantUML diagrams online it’s better for usability and security reasons to install a local server. And this approach is important if you plan to generate diagrams with sensitive information. The easiest path is to run PlantUML Server Docker container and configure localhost as server.

docker run -d -p 8080:8080 plantuml/plantuml-server:jetty

In VS Code config, open user setting, and configure like:

"plantuml.server": "http://localhost:8080",
"plantuml.render": "PlantUMLServer",

Now to preview diagram in VS Code press alt-D to start PlantUML preview.

PlantUML preview in VS Code and local server

You can also generate diagrams from the command line. First download PlantUML compiled Jar and run the following command which will look for @startXXX into file1, file2 and file3. For each diagram, a .png file will be created.

java -jar plantuml.jar file1 file2 file3

The plantuml.jar needs Graphviz for dot (graph description language) and on macOS you can install it from Homebrew: brew install graphviz.

For processing a whole directory, you can use the following command which will search for @startXXX and @endXXX in .c, .h, .cpp, .txt, .pu, .tex, .html, .htm or .java files of the given directories:

java -jar plantuml.jar "directory1" "directory2"

Maintain source-controlled diagrams as a code

Documentation and drawing diagrams can be simple and maintaining source-controlled diagrams with tools like PlantUML and mermaid is achievable. These tools are not like the behemoth of Sparx Enterprise Architect but provide light and easy way to draw different diagrams for software development. You don’t have to draw lines and position labels manually as they are magically added where they fit and you even get as crude boxes and squares as thousands of dollars more expensive tools. Now the question is which tool to choose: PlantUML or mermaid?