The Story of Third-party JavaScript

It’s been 10 years since myself and Anton Kovalyov published Third-party JavaScript (Manning, 2013). As far as I know, it’s the first and only book dedicated entirely to teaching readers how to build JavaScript applications that execute on someone else’s web pages. Applications like embedded widgets, analytics scripts, and yes, ads.

Anton and myself were interested in the topic because our day job was working at Disqus, the embedded commenting platform. At the time there really wasn’t a guide for how to solve a lot of the problems we were facing. Problems like how to make XMLHttpRequest POST across domains, or how to safely run JavaScript code on pages where basic functions like Array.prototype.pushhave been replaced with custom incompatible versions. We spent a lot of time – and sometimes late nights – figuring out those answers.

If we could go back in time to when we first started working at Disqus, what would be the book we’d give ourselves? That was the idea behind Third-party JavaScript. We wanted to build the missing guide for programmers operating in our small (and unloved) web development subfield.

But we didn’t wake up one morning and decide on that pitch, or even plan to write a book at all. A series of events led us to even thinking of writing one. And it would take years after that before we’d hold the book in its final published form.

In this post, I wanted to revisit some of the story behind Third-party JavaScript: where the idea came from, how we came to talk to publishers, the process of writing the book, how it sold, and finally, explore its lasting ramifications. Whether you’re a prospective book author, a third-party scripter, or just curious about JavaScript community history, I hope you’ll find it mildly interesting.

It started with a conference talk

It was summer of 2010. I was just a few months into working at Disqus, whom I had joined after spending 3 years doing traditional LAMP stack + “AJAX” development at FreshBooks in Toronto.

I was now working nearly 100% in JavaScript on “hard mode” — writing an embedded application that had to work on other people’s web pages, while simultaneously supporting browsers as old as IE6. The job was pretty challenging, but I was pretty determined to “make it” in San Francisco at a YC company, so I was working hard and even catching up during evenings.

Disqus is where I first met my future co-author, Anton, who’d already been working there a year before I showed up. It’s Anton who first introduced me to the Disqus codebase, walking me through how they’d made an entire commenting and moderation UI that loaded via a single third-party <script> tag. We literally sat side-by-side, often working together on the same projects, and frequently conferring with eachother on ideas, code, and typical programmer bikeshedding.

Like every other web app at the time, Disqus used jQuery, and the official jQuery Conference had just put out a CFP for their upcoming Fall conference in Boston. I had the idea that if the things I was working on were interesting to me, maybe it would be interesting to others? I submitted a talk proposal titled “Building Distributed JavaScript Widgets with jQuery”. The idea was that I would walk the audience through the end-to-end development of a simple star-rating widget with code examples in JavaScript and PHP.

The timing probably couldn’t have been better. The Facebook Like button had been out for a year at this point, and Twitter had just launched their own 3rd-party Tweet button. On top of that, Disqus itself was having a moment. Many web development thought leaders were switching their blogs to static site generators like Jekyll, and they began using Disqus to host dynamic comments on otherwise-static HTML documents. This blog included.

Still, I was surprised when the talk was accepted and announced that September as part of jQuery Conf Boston 2010. You can view the slides here. It covered some of the things I’d learned that year, like how to use JSONP, window.postMessage, and why iframes are so important. It was also my first conference talk, and I wanted very badly not to embarrass myself in front of a room of smart people. I ended up missing much of the conference, opting instead to practice repeatedly in front of my hotel room’s bathroom mirror.

Overall, I thought the talk was received pretty well. I got a few good questions, and someone commented on Twitter about my delightful Canadian pronunciation of the word “JavaScript”. I also took part in a cool speakers’ dinner where I met some amazing people I’d only seen on blog posts and Twitter before. The experience was great, and I left Boston on a post-conference high.

I don’t remember leaving the conference with any grand ambition to continue this work. But a few months later, I received an email that would dramatically change the trajectory of the next few years.

“Have you considered writing a book?”

It was now January 2011, and someone at Manning Publications sent me an email. They were emailing folks who had presented at jQueryConf the previous fall to see if anyone was interested in developing their talk material into a book.

“Was that something you wanted to explore?”

I can’t remember the exact order of events, but it’s at this point that I approached Anton to write the book with me. We’d been working together for the past year now, the jQueryConf talk content was based on both of our work, and he assisted me in vetting the slides. But perhaps most importantly, I wanted Anton because I didn’t think I could do it alone.

Now, even though Manning had approached us initially, we still had to convince them there was a book here. And it turns out, that if you’re the first to do something, publishers are a little nervous about producing that content. “Why doesn’t O’Reilly already have a book on this?” felt like a challenge we had to overcome. It didn’t help that there was scant evidence of the topic even being a thing at all; in 2011, the term “Third-party JavaScript” only returned a handful of Google results.

To do that, we filled out a standard template provided by Manning where we had to explain the book’s title, who it’s for, what readers will learn, highlight any competing books, etc. Manning also wanted a detailed table of contents, for which you were expected to define not just each chapter, but each chapter’s sections and subsections. This was to demonstrate that you had enough content to fill a 300 page book, which was kind of a must at the time (the sub-100 page book market that O’Reilly would later pioneer hadn’t happened yet).

You can read this original proposal here.

On the strength of this proposal and our passionate conference-call gesticulating, Manning decided to go forward. And what started as a conference talk proposal just 6 months earlier had turned into a contractual obligation to deliver a 300 page book. What had we wrought?

Actually writing a book

One of the reasons we wanted a publisher is that even though there were two of us, Anton and I did not have a lot of confidence that we could actually write an entire book ourselves. We had read more than a few “so you want to write a book” blog posts, and as a result we weren’t deluded about the colossal scope of work we were taking on. We wanted all the help we could get.

Manning and most other publishers have systems for developing books, and by agreeing to publish a book with them you’re agreeing to use that system. For example, Manning pairs you with an editor and some handlers, commits you to a schedule for delivering chapters, and they have a process for getting feedback from readers early and often. The book becomes available for purchase early as part of their Manning Early Access Program (MEAP), and folks have a chance to read early chapters and comment before the book is finished. Access to this “Manning method” was a big plus.

When it came to the actual writing, Anton and I decided that the fastest way forward was to divide the book up. Each of us would tackle different parts, playing to our strengths. I focused on the early chapters, setting up the example application the reader would be building over the course of the book, as well as the initial concepts (loading scripts, Same-Origin Policy, JSONP, etc.). Anton worked on the middle and later chapters (e.g. Performance, Security, etc), which had more technical focus.

Joining us from Manning’s side was Renae Gregoire, who was simultaneously our editor, book-writing spirit guide, and taskmaster. She taught us how to write better by using Manning’s house style, let no reference go unexplained, and was diligent in reminding us about our many deadlines.

Writing the first chapter was probably the hardest. Not only did we have to learn how to actually write, we also had to set up the storytelling that would set up the rest of the book. What exactly was this book about, and what would readers learn by the end? Just getting the definition of “third-party JavaScript” alone seemed to take forever, especially since no consensus definition existed at the time. I probably rewrote that section a dozen times.

I can’t speak for other technical authors, but Anton and I did not have all the answers in our heads. We often had to get those answers, by researching, tinkering with code, and consulting with peers. We did not want to come off as frauds, so we implemented every example and technique presented in the book (as one should!), and shipped those as part of the the accompanying source code. This all took a lot of time.

Despite our best efforts, we were behind schedule almost from the very beginning. But after we delivered the first 1/3 of the book, we felt like we were getting the hang of things and progress became a lot more steady.

By March of 2012 – one year after we’d signed the contract with Manning – we had delivered drafts of all 10 chapters (albeit, in varying states of quality). MEAP readers already had access to the first 6 chapters, we were approaching 1,000 preorders, and Anton and I felt ready to pop the champagne.

The remaining 10%

The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time. — Tom Cargill, Bell Labs

This quote may have been referring to software development, but I think it equally applies to book writing. Even though we had “finished” all 10 chapters in one year, it would be another year until the book actually went to print.

A key reason for this slowdown was how the book itself was being assembled. At the time, Manning used an in-house XML schema to structurally represent the content, which aided them in publication (and necessary for producing early-access editions). Writing an entire book in XML wasn’t appealing, so Anton and I would write our initial drafts in Google Docs, and only convert them to XML after our editor had made a few passes. But once these XML files were stored in Git and became the source of truth, any subsequent editing had to happen there.

That worked great in the beginning, but now that all 10 chapters were done, we had to go back repeatedly and edit XML without the benefit of a word processor. And boy, did we have to do a lot of editing:

• adjusting the book’s voice to sound like a single person
• fixing flaws and typos pointed out by reviewers
• adding and revising diagrams, code samples, etc.
• rewriting whole sections that didn’t work, then going through the entire book to remove any references to those sections

Doing all of this in XML made the work a real slog. And the way the review cycle works, where you hand in early access versions to reviewers, wait weeks for feedback, make edits, and repeat, was adding to the challenge. It felt like trying to land a monster 50,000 line PR that was stuck in code review hell, and after going back and forth for months we just wanted to hit merge and move on with our lives. We were crawling towards the finish line.

Another minor point of stress was that deep into development, Manning wanted to revisit the title – even after the book was available in MEAP and had been pre-ordered by readers. Without going too deep, I feel they were concerned that the current title was too niche, and wanted to broaden the subject matter to appeal to a wider audience (read: sell more books). They suggested a handful of alternative tites, some of which dropped “third-party” entirely. But Anton and I were pretty resolute that we wanted to produce an authoritative book on this subject matter, and that “Third-party JavaScript” would best capture that.

In the end the Manning stuck with our preferred title (🙏). We instead tried to broaden the subject matter as much as possible, by highlighting every possible use case, making sure the sample code worked on Windows, and even added adjacent content (e.g. a chapter on Testing).

We tried to make it accessible as we could. But was it enough?

The reviews are in

The book came out in March 2013, almost exactly 2 years since the contract was signed. Disqus hosted a launch party for us in San Francisco (they were supportive of the project beginning to end). Manning sent Anton and myself about a dozen copies each, which mostly found their way to friends and family. I only signed a handful, so if you’ve got one, hang onto it!

Despite my minor grumblings, I feel working with Manning was a net positive. I’m not sure we could have done it without them, really. 100% if we had tried to Kickstart this book, I am confident it would have been vaporware and we’d be accused of embezzling Kickstarter funds.

And ultimately, Manning’s concerns about the lack of broad appeal were valid. Consider this review from Raymond Camden in 2013:

On the surface, you may think that such a book would have limited appeal. Many of us write JavaScript and many of us may even use such third-party tools, but the percentage of those who need to author such things is probably pretty limited. In my years in web development, I’ve never had a client ask me for one and I’ve only built one once. (See this blog entry on a Behance widget I built.)

This summarizes the challenge well: Raymond didn’t think there would be anything in this book for him. And yet …

I cannot stress how wrong I was. While certainly the book does focus in on embedding code in other web sites, the level of detail and coverage of various browser quirks makes this book invaluable to anyone.

… If you have no plans ever for building a third-party API, this book is still strongly recommended. Hell, the last two chapters alone on performance and debugging are worth the price of the book alone. This is a book I plan on keeping nearby as I feel like I’ll be tapping the knowledge inside again and again.

Some other reviews (I’m trying not to cherry pick):

• Review: Third-party JavaScript – Marcus Christie (2020)
• Book Review: Third Party JavaScript – Gary Sieling (2016)
• Goodreads – currently 4.08/5 with 48 ratings

I think in the end the book was pretty good. I’ve flipped through it a few times recently and wasn’t immediately filled with shame. We’d somehow strung together 270 pages (a little under our goal of 300) – plus dozens of accompanying code snippets and diagrams – into a semi-coherent guide on Third-party JavaScript.

Did people read it?

As of today, Third-party JavaScript has managed to sell roughly 4,500 copies (about 50/50 print and digital). My sense is that’s not bad, or at least it was enough that Manning approached us some time later about doing a 2nd edition. The international editions, of which 3 were made, probably contributed just 10% of that. It also appeared on O’Reilly’s Safari Online at some point, and certainly folks read pirated copies too.

While it may not have been a runaway success, I do think it was successful in one critical way: the book helped define “third-party JavaScript” (lowercase) as a concept.

If you Google the term today, you’ll find the book, but also a number of credible developer education sites that explain and expand on what third-party JavaScript is. Back in 2011, the same query would net you a half-dozen results at most. It’s not that the content wasn’t out there – it was just scattered on different blogs and Stack Overflow answers, and not so cleanly categorized as “third-party javascript”.

I don’t think this subsequent legitimization of “third-party JavaScript” is a coincidence. Our book became required reading at a number of companies and software teams operating in this space. I was once informed that teams at Google used the material. At least a few thought leaders picked up copies (probably for Paul Irish’s foreword). And years later, I find distinct language from the book appear in modern blog posts, aligning on the same definitions we helped formalize.

This is how I view the legacy of Third-party JavaScript. While it only sold a modest number of books, and the content is now largely out of date, it succeeded in a way Anton and I hadn’t really anticipated: it helped define and legitimize a small but important subfield of our industry. Were it instead titled “Building Distributed JavaScript Widgets”, I don’t think the same would be true.

Our post-book periods

By the time the book had come out, Anton was already better known as the creator of JSHint, a static type checker that began as a fork of JSLint. JSHint was really a pioneer in driving people away from the “best practices-or-bust” approach of JSLint. It was superceded by ESLint, for which extensive configuration was a signature feature. There’s a lot more I could write about JSHint, but I’ll leave that for Anton.

Almost immediately after the book came on, Anton signed on to another book project: Beautful JavaScript. Anton had convinced the folks at O’Reilly that JavaScript was worthy of an entry in their Beautiful series, and chased down some pretty influential people to contribute chapters. I was really happy to be included in this project, even if it was a result of being Anton’s former co-author and friend.

As for me … After the book came out, I started going on the speaker circuit for a few years. Some conferences would invite me (super flattering), but most I probably wrote CFPs for. As before, most of the content came from new problem areas I was solving during my day job, like Content Security Policy, or how to replicate the briefly-exciting-but-now-dead seamless iframe attribute.

Many of those conferences were outside of San Francisco, and a few were in other countries. This got me out of my comfort zone and traveling a lot, which was great. I met some great JavaScript community members along the way, some of whom still occasionally like my quips on Twitter.

Career-wise, Third-party JavaScript ended up being a key part of every job I’ve held since. At Shape Security I worked on WAF-injected third-party scripts that helped to defeat unwanted bot automation. At Sentry, I worked on our third-party browser JavaScript SDK to capture better stack traces from browser apps. If my writing continued in any notable form, it did so on Sentry’s blog, where I’ve continued my coverage of estoric JavaScript topics like deep diving on window.error, source maps, and distributed tracing. I’m still at Sentry today.

Closing thoughts

Writing Third-party JavaScript was a colossal amount of work. I probably earned only ~$1/hour for the effort, and there were many nights where all I wanted was it to be done with it.

Now 10 years later, I look back at the whole thing positively. Besides furthering my expertise as a niche JavaScript developer, I learned how to build convincing proposals, became a better writer, grew my industry connections, and helped build confidence that I could deliver on big, multi-year projects. The minor notoriety of having “written a book” didn’t hurt either. These outcomes meaningfully altered the trajectory of my career for the better, and I’m grateful.

I guess this turned into my own “so you want to write a book” story. I hope it serves as a mildly interesting example of how people get involved in programming topics, and what can happen should they pursue sharing what they’ve learned with the broader community.

If you’re working on something you find interesting right now, I encourage you to consider that there are probably people out there who’d like to hear about it. Consider blogging about it, or sharing a quick video on socials, or maybe even putting together a conference proposal. You never know where it might lead!