My Twitter ad blocking experiment, DOM manipulation in someone else’s React app

Twitter as a platform is pretty neat. Twitter as a company… has its problems.

A while back they started showing ads into my timeline, which is something I'm really not here for. I would gladly pay a fee not to have that because I love the platform, but y'know. Corporate bullshit 🙄

So I've been taking it out on the advertisers audacious enough to target me, by blocking them. Apple? Blocked. Amazon? Blocked. Intel? You betcha you're gonna git blocked.

Despite my best efforts it got to the point where I was getting way too many ads to keep up with, so I decided to write a script to do it automatically.

TL/DR: I just want to install the ad blocker extension

There's an extension you can install to auto-block Twitter advertisers (providing you're using the mobile site). You can get this for:

Update 2019: I've taken it down because it stopped working.

Automating actions in someone else's react site 🤔

I mainly use the mobile Twitter site because it's way faster than desktop, but it's one of those sites that use post processing to munge class names. So instead of seeing nice
<div class="tweet"> HTML, you get something more akin to <div class="rn-1oszu61 rn-1efd50x rn-14skgim rn-rull8r []…]">

This makes it insanely difficult to automate the process of finding an ad and
blocking it. I'm not sure what ad blockers are doing, but this requires some
pretty specific DOM selection to get working.

There's two approaches you could take:

  1. Loop through all the <div> elements on the page until you find one with the
    text you're looking for. Eg. "promoted".
  2. Use weirdly specific selectors that get the job done, almost by chance.

Despite making fun on Twitter I chose the latter, because Twitter uses inline SVG elements, which means we can find promoted tweets by querying for the presence of certain SVG paths. It's completely absurd and I think React is criminally negligent for making this a standard practice.

Here's the two main selectors I'm using to find interface elements on Twitter mobile:

// The "promoted icon"
const adSelector =
  'path[d="M20.75 2H3.25A2.25 2.25 0 0 0 1 4.25v15.5A2.25 2.25 0 0 0 3.25 22h17.5A2.25 2.25 0 0 0 23 19.75V4.25A2.25 2.25 0 0 0 20.75 2zM17.5 13.504a.875.875 0 1 1-1.75-.001V9.967l-7.547 7.546a.875.875 0 0 1-1.238-1.238l7.547-7.547h-3.54a.876.876 0 0 1 .001-1.751h5.65c.483 0 .875.39.875.874v5.65z"]';

// The dropdown chevron
const dropdownSelector =
  'path[d="M20.207 7.043a1 1 0 0 0-1.414 0L12 13.836 5.207 7.043a1 1 0 0 0-1.414 1.414l7.5 7.5a.996.996 0 0 0 1.414 0l7.5-7.5a1 1 0 0 0 0-1.414z"]';

The remainder of the extension is fairly straightforward. Find stuff, click stuff, you know the deal. If you're interested in having a play with it yourself, you can check it out and give it some stars on Github.

Proofer: an API Blueprint renderer

I'm a big fan of good documentation. It's hard to do, and doubly so with poor tools.

At work we've been using API Blueprint for documenting our systems, and while it's been serving us well, the tooling leaves me wanting more.

Some of the problems I have:

  1. Responsiveness: I don't mind a slow compilation step, but a lot of the tools struggle with large files, leaving a slow page render and no free RAM on my system
  2. Automation: I want to build my API docs from a GitHub repo and push them wherever. There are tools like Aglio that can do this, but the output is visually very dated and incredibly slow
  3. Readability: Apiary is beautiful but doesn't support automation super well, since it primarily wants to be an online editor. None of the third party tools come close in terms of features or general experience.

With that in mind, this weekend I figured I'd try my hand at generating some docs using Ractive (the virtual dom-like mustache templater) and Bootstrap 4.

Proofer (a frontend to Drafter)

The result of my work is a little project called Proofer (a frontend to Drafter) with the aim of letting developers quickly create and manage templates to render documentation.

It has two parts

  1. A backend renderer which renders an API Blueprint file into a JSON equivalent
  2. A frontend render which takes the JSON and outputs HTML

It uses the emscripten-compiled Drafter.js library rather than the full-fat C build, because npm packages with a compile step jangle all my pet peeves.

This also means that in the future we can implement client-side authoring and intelligent differential updates using Ractive (which as an aside is something that I'd like to see Apiary do too).

Sample render


So how does this implementation stack up?

It's a client-side rendered single page app which definitely satisfies the responsiveness criteria. Only the stuff you're interested in gets loaded into the DOM, and the content is only rendered as you navigate between categories. This is lightning fast on an initial page load.

Page render for a large API completes in under a second

You can see that the render of our large API Blueprint akes less than a second. There's a fair bit of JS parsing waste that could possibly be fixed with an async load, but this is not too bad considering our existing render takes a good twelve seconds thrashing around with jQuery UI before the page is loaded.

Our existing API docs SUCK

I always noticed, but never realised just how slow our existing docs had become.

(An amusing aside, the Apiary editor had crazy memory leaks and would chewing up gigabytes of RAM editing our documentation in Chrome before we moved authoring to GitHub.)

Other niceties

In terms of readability, this is wholly subjective. I don't think the layout is super amazing, but It's using Bootstrap 4 for styling which I think is a good base to work on, and it's something I'll continue to develop.

One of the killer features though, is the integration of Ace Editor for payload rendering. You can click “view in editor” on any JSON glorb to open it up in Ace where you can quickly search, edit, do code folding etc. For APIs returning large payloads, this is priceless because standard JSON rendered into the page is really hard to navigate.

Finally, in terms of automation this isn't quite there yet. While it has the command line app for the build step, I'd like to split out the components so others can easily build their own documentation. At the moment this is still tightly coupled, though won't be difficult to break up.


Interestingly, the easiest part about this project was the parsing since the heavy lifting had already been done by the good folks at Apiary.

The toughest part is styling the output to be both visually pleasing and useful, something that I'm planning to continue working on.

Ultimately the most important part is having the documentation in the first place. I've joked with my colleagues about quitting my day job to follow my passion of being a technical writer… but for now I'll stick to doing both.

You can fork the project on GitHub or see some preview output of a fictional API.

Follow @ashkyd