Building an Office Add-in using SPFx

Office Add-ins, or more specifically Office Web Add-ins, are an extension for Microsoft Office applications like Outlook, Word, Excel and PowerPoint. The idea is that instead of building a desktop application or a stand-alone web application, you bring your solution to the user right inside the Office application they are using every day. And there are a lot of people using Office - well over a billion in fact, and the vast majority of people in businesses. So that makes Microsoft Office a great platform for delivering software solutions, in much the same way that web applications use the fact that most people already have a browser installed.

Of course this idea isn't new, and there have been many technologies for extending Office, including COM and more recently VSTO (Visual Studio Tools for Office). But these have the drawback that they don't run everywhere Office runs, which isn't just Windows desktops, but also mobile devices and the web. That's where Web Add-ins work really well, because they are really just web pages or web sites surfaced inside the Office application, and using a JavaScript library called Office.js to get at the context of the application and the document content.

This gives you the freedom to use pretty much any web hosting technology you like, along with client-side technologies like ReactJS and the Office UI Fabric to give the consistent look and feel that users expect. You can find out more in another article.

But what if we could just use SPFx?

In that article I suggested that if you have been doing SPFx (SharePoint Framework) development, then you already have all the skills you need to build Office Add-ins.

But what if you could use SPFx components directly? Let's think about the implications. With Office add-ins you need to decide where to host the web content that will be rendered. A lot of people have set up a web site on Azure or another cloud provider using the Platform-as-a-Service model, which makes it really easy to provision a web site using various web development stacks. That is to say, it's easy compared to standing up a web server in the old on-premises world. But you still have to find somewhere to host it, and then set it up and maintain it.

But if you're using Microsoft 365 then you already have a web-site provisioning solution that requires zero effort to set up and maintain - you have SharePoint! What if you could use your existing SharePoint infrastructure directly to do the web hosting, and use the SharePoint Framework to do the provisioning? And what if you could then take advantage of all the SharePoint Framework libraries like MSGraphClient or the PnPJS library to get at Microsoft Graph data without having to worry about all the authorization code? That would be two major problems solved at a stroke.

Getting Started

First, make sure that you have version 1.10 of the SharePoint Framework or later, along with all the other pre-requisites - set-up instructions here if you need a reminder. To use the preview feature, you also need to add the --plusbeta argument to the Yeoman generator:

yo @microsoft/sharepoint --plusbeta

The result of this will be an extra folder and XML manifest file in the scaffolded solution (yes, Office add-ins preceded the JSON popularity wave). You'll want to create a web part and also make sure to select the tenant scoped deployment option, in the same way as when building for Teams (otherwise deployment gets complicated).

Inside your code you can use the Office.js library if it is running as an Office Add-in, so you'll probably want to install the typings:

npm install @types/office-js --save-dev

If you want your SPFx web part to detect whether it's running as an Office Add-in you can look at the context:

if(this.context.sdks.office) { 
    var currentMailbox = this.context.sdks.office.context.mailbox;
    /* do stuff with mailbox */ 
    }

Yes, that's right - you get the web part context to get to Office.js, and then office has its own context.

A great way to get going with Office.js is to play around with the samples that come with the Script Lab tool. Script Lab is itself an Office Add-in that you can use to build add-ins - a meta add-in, if you will. It runs right inside the Office application and has a built-in code editor. Script Lab for Outlook has recently become available, and can be installed just like any other add-in from the store. You can also use Script Lab as a prototyping tool, and then paste your Office.js code into your SPFx solution.

Currently there isn't really anything equivalent to the SPFx workbench for testing locally, although there's nothing stopping you using the context to load some dummy data if you're running in SharePoint, and test the UI in the workbench that way.

Deployment

Once you've got something working, you probably want to deploy it and test it in Outlook for the Web (the only supported client at the time of writing). The first step is to deploy the solution to the SharePoint App Catalog as normal, choosing the tenant-scoped deployment option (which will be available if you enabled it as described above).

The second step is to sideload the add-in in the Outlook web application. To do this you need to go to menu at the top of any message and choose the ellipsis (More actions):

Choose the 'Get Add-ins' option from the menu and choose 'My add-ins' and then 'Add a custom add-in' and finally 'Add from file...'. At this point you need to choose the add-in manifest file from your officeAddin folder. This will point to the URL where your SharePoint web part is hosted. You'll then need to click through a warning and the add-in should be available with the name "SPFx template", or whatever you changed this to in the manifest file.

This is not the end of the deployment story, by the way; it's just for the preview and will likely change over time. Speaking of which...

It's Still Early Days

Bear in mind that (at least at the time of writing) the feature for building SPFx solutions for Outlook is still in preview, and currently only works for Outlook Web Access. In the future we should see this become 'general availability' and also see this extended to other Office applications like Word, Excel and PowerPoint.

Universal Web Parts?

Theoretically, you could build an SPFx web part and make it available in Teams, SharePoint and Outlook. But does that really make sense? It all depends on exactly what you're trying to build. It might work, but these are three quite different applications and, frankly, it's pretty unlikely that the same functionality or UI would make sense to the end user in all three places. A better approach is to design for each of those platforms and focus on trying to do one thing well, rather than attempting to come up with some universal extension that can do lots of things in different contexts. Think of this as more of an opportunity to re-use your development skills with the possibility of some code re-use as well.

Next Steps

You can find a full set of instructions for getting started with Outlook add-in development using SPFx on docs.microsoft.com. If you don't have a Microsoft 365 account you can get a free one by joining the Microsoft 365 Developer program. And if you're already building SPFx solutions for Microsoft Teams or SharePoint, you can add a third string to your bow simply by adding another manifest!