Office Add-In Development: The Need for Office.js

Recently I had the opportunity to do a little (and I mean “little” in the most literal sense) Office add-in development. If you follow me on this blog or Twitter, you know that I work primarily in the Azure space. Building an Office add-in is certainly new to me, but I figured it would be kind of fun to learn about something new. This journey started as a result of a partner that I worked with who was having problems getting their add-in to load correctly in both Word Online and Word (on their desktop).  Odd . . . right?  It should work the same when hosted in both Office Online apps and Office.

I knew from prior reading, that the “new” Office add-in model was (to likely over simplify) essentially creating a web application that would be hosted within an Office desktop (e.g. Word 2016) or Office online (e.g. Word online) application. If the add-in needed to interact with the Word, Excel, Outlook environment in any way, there is a JavaScript API to do so. Seems easy enough.

To get started, I did a little Binging (just sounds odd . . . but whatever) for Office add-in development. I wanted to start with “official” Microsoft documentation, so I ignored results from and blogs (wait . . what if it is my blog . . .this blog . . .)  One of the top results was the “Office Add-ins platform overview” page at  Sweeta!

Reading . . .reading . . . reading

Finally, I get to something that looks like code  . . .well at least a picture of code, at  This section states that the minimal version of an add-in is a “static HTML page that is displayed inside an Office application, but doesn’t interact with either the Office document or any other Internet resource.”  I can do that!  I’ll simply write a “Hello World” app to just see it work, and then go from there.  The page includes a picture of two components needed for a “Hello Word” Office add-in, the manifest file and the web page.  Bam!


I created the most basic HTML page . .  . which just happened to look exactly like the one in the picture. I then proceeded to read up on how to debug the add-in via sideloading the add-in via Office and Office Online.  This is easy!

I started by sideloading the add-in via Word (desktop). Hot damn . . . it worked!!


I then decided to push my luck and try it on Office Online.  FAIL!


Ok . . . so hit the “RETRY” button? Wait for the spinny icon to go away . . . . FAIL, again!


Ok . . . . um. . . . WTF?  Hit “START”?  Sure . . what’s the worst that could happen?  It worked!!


This is where, as a developer, I start to question my life choices. I also realize there must be something else going on causing this funkiness. I tried the normal browser rotation game – Chrome, Edge, IE – all produced the same results. Hmmmm.

I decided to do some more reading. I found this page,, which promised to give me a working sample. I followed it, and it worked. So, what was different (besides being a whole lot more code)?  As I dug around the generated code, I noticed the home.html file contained two JavaScript references, one for jQuery and one for office.js. I could understand the jQuery one, but what’s this office.js thing?  It must be the API used to interact with Office apps. Ok . . . but my “Hello World” app isn’t doing anything with Office apps.  What gives?

This lead me to discover the “Understanding the JavaScript API for Office” page.  I noticed this block of seemingly normal text:

“All pages within an Office Add-ins are required to assign an event handler to the initialize event, Office.initialize. If you fail to assign an event handler, your add-in may raise an error when it starts. Also, if a user attempts to use your add-in with an Office Online web client, such as Excel Online, PowerPoint Online, or Outlook Web App, it will fail to run. If you don’t need any initialization code, then the body of the function you assign to Office.initialize can be empty, as it is in the first example above.”

YES! YES!!  That would have been good information a few hours ago . . . . as on that “Hello World” page with the simple HTML example code.  Put some big, red blinky arrows around this, for Pete’s sake!

I proceeded to add the most basic office.js initialization code to my sample “Hello World” page (which just happens to be hosted on Azure Web Apps, with a local Git continuous deployment option . . . see, I had to get Azure in here somewhere).


I proceeded to reload my add-in in Word online. It worked!  The simple console.log() statements showed up in the JavaScript console too. Yippie!!



That’s a lovely story . . .what’s the point?

If the documentation example seems too simple to be true, it probably is?  Eh . . . sometimes.  The point here is that for Office add-ins, you are absolutely required to reference office.js and at least set up an empty initialization block.  Doing so helps Office in setting up some of the logical infrastructure needed for the add-in environment. It’s like magic. Only magic isn’t real. Mostly.