The Book

Having answered well over 100 questions about Office.js on StackOverflow, I realized the need for a definitive guide to Office.js key concepts.  Initially, I planned to outline these concepts in the form of a short blog post.  Pretty soon, though, I realized that in order to adequately cover all these interesting and interlinked concepts, I needed a full website.  As I continued writing, it became clear that there were many other auxiliary topics, tidbits of advice, and deep-dives into the underlying architecture that were well beyond what I had intended for this site.  And, so, the book was born.


Buy the book at

The book is not an API reference manual.  The individual APIs are well-documented in online reference topics on  Instead, my focus is to describe the underlying principles that these APIs have in common, expanding — far beyond the content on this site — upon the concepts, tools, and techniques for authoring Office Add-ins.

Importantly,  this book is published using a “lean” methodology – publishing early, and publishing often.

Since writing the book is strictly my “moonlighting” activity – my day-job is to be a developer on Office.js APIs, not a technical writer – it will take a good long while before I am actually “done” with all the content I want to write about. I would much rather ship an early version of the book, addressing the most common questions and issues that I see folks struggling with, and then keep iterating on it from there.

In buying this e-book through LeanPub (where I’m also discounting it for the “early readers”), you are entitled to free updates to the book. So, expect to see more content appear month-to-month (and, if you sign up for email notification, to receive periodic emails updates about what new content got added).  Note that there are also a number of sections that I’ve already written, but haven’t ported to LeanPub quite yet (I will do this in the coming weeks).  So, feel free to buy the book now, and then see more and more content light up as times goes on!

I welcome any and all feedback about the writing, explanations, code-samples, and whatever else. I also welcome topic suggestions, if you see something I didn’t cover.  The best way to reach me is at

The book’s table of contents, for all written-and-already-published topics, is pasted below.

  • 1 The book and its structure
    • 1.1 The “evergreen”, in-progress book
    • 1.2 Who should read this book
    • 1.3 From the author
    • 1.4 Book structure
    • 1.5 A few brief notes
    • 1.6 Acknowledgments
  • 2 Introduction to Office Add-ins
    • 2.1 Chapter structure & planned content
    • 2.2 What’s “new” in the Office 2016 APIs (relative to 2013)?
    • 2.3 What about VBA, VSTO, and COM Add-ins?
    • 2.4 Office.js: The asynchronous programming model
      • 2.4.1 Why is Office.js async?
      • 2.4.2 What is meant by “the server”
    • 2.5 A word on JavaScript and TypeScript
    • 2.6 “But can Office.js do XYZ?”
  • 3 Prerequisites
    • 3.1 Chapter structure & planned content
    • 3.2 Walkthrough: Building an Add-in using Visual Studio
  • 4 JavaScript & Promises primer (as pertaining to our APIs)
    • 4.1 Chapter structure & planned content
    • 4.2 “JavaScript Garden”, an excellent JS resource
    • 4.3 Promises Primer
      • 4.3.1 Chaining Promises, the right way
      • 4.3.2 Creating a new Promise
      • 4.3.3 Passing in functions to Promise .then-functions
      • 4.3.4 Advanced topic: the “gotcha” of using class-member functions in a .then
  • 5 Office.js APIs: Core concepts
    • 5.1 Chapter structure
    • 5.2 Canonical code sample: reading data and performing actions on the document
    • 5.3 (, etc.)
    • 5.4 Understanding proxy objects
      • 5.4.1 Proxy objects: the building-blocks of the Office 2016 API model
      • 5.4.2 The processing on the JavaScript side
      • 5.4.3 The processing on the host application’s side
      • 5.4.4 Proxy object identity
    • 5.5 Loading properties
      • 5.5.1 The object.load("property-names") method call
      • 5.5.2 Scalar vs. navigation properties – and their impact on load behavior
      • 5.5.3 Loading and re-loading
      • 5.5.4 Beware misspellings!
      • 5.5.5 Loading collections
      • 5.5.6 Loading on methods versus properties
    • 5.6 Values that load automatically (ClientResult-s)
    • 5.7 Syncing object state
      • 5.7.1 De-mystifying context.sync()
      • 5.7.2 Returning the context.sync() promise
      • 5.7.3 Passing values across .then-functions
      • 5.7.4 Real-world example of multiple sync-functions
      • 5.7.5 When to sync
      • 5.7.6 The final context.sync (in a multi-sync scenario)
      • 5.7.7 A more complex context.sync example:
    • 5.8 TypeScript & Async/Await
    • 5.9 Catching errors
  • 6 … More chapters to-be-ported into this book soon! …