Create Outlook Add-ins using SharePoint Framework

Introduced in SharePoint Framework v1.10, you can implement an Outlook Web App add-in with the SharePoint Framework and use SharePoint as a host for your solution.

Using the SharePoint Framework as the platform for your Outlook Web App Add-ins includes the following benefits:

  • The development model is similar to SharePoint Framework web parts
  • The same code can work across SharePoint, Microsoft Teams, and Microsoft Office
  • Your add-in is automatically hosted for the tenant without requiring you to provision any additional services
  • Simplified authentication to access different services in Microsoft 365
  • You can benefit from the same permission and access management model as within SharePoint, with easy access to Microsoft Graph APIs and other services

Note

This feature is currently in developer preview feature. In order to use features in developer preview, ensure you use the --plusbeta version of the package. For more information, see: Try SharePoint Framework preview capabilities.

Note

During developer preview, this feature is only supported in Outlook Web Access. Once this feature reaches general availability, it will be supported across all Office desktop and web clients.

Development process

You can start developing Outlook add-ins simply by using the SharePoint Framework v1.10 or later versions. To use this feature in developer preview, you'll need to include the --plusbeta argument when executing the Yeoman generator:

yo @microsoft/sharepoint --plusbeta

This will create an Office Add-in manifest file for the solution in a new folder called officeAddin. This file is automatically generated with default settings, which enable your web part to be used in the Outlook Web App as a Task Pane extension.

You'll need to deploy the solution to a tenant using the tenant scoped deployment option to ensure that the component can be found in the context of the add-in URL as defined in the manifest XML file. This setting can be adjusted in the package-solution.json file by updating the skipFeatureDeployment as true.

Note

For more information on the manifest file, see: Office Add-ins: Office Add-ins XML manifest.

Use the Office JavaScript SDK (Office.js) in the web part code

Before you can use the Office JavaScript SDK in your code, you'll need to include the correct types for the solution. You can install the latest types by adding the @types/office-js package to your solution with the following command:

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

You can detect if the web part is executing within the Office context by using page context as shown on the following property, which refers to the Office JavaScript SDK. This property value is dependent on the context where the code is being executed.

this.context.sdks.office

For example, you can access the mail inbox using following property:

this.context.sdks.office.context.mailbox

Note

For more information on the Office JavaScript API capabilities, see: Office Add-ins: API Reference documentation.

Configuration support with Office Add-ins

Office Add-ins built with the SharePoint Framework support a one-time configuration option when the add-in is initially viewed. This is an optional capability, which can be controlled from the add-in manifest file. The configuration option is controlled in the URL of the solution in the manifest file. By default the configuration option is enabled and the URL is as follows:

https://{tenant}.sharepoint.com/_layouts/15/outlookhostedapp.aspx
  ?componentId=c76ba09e-4068-4233-b342-aedfc75a6578&isConfigureMode=true

If your add-in doesn't have any initial configuration options, you can remove the isConfigureMode query parameter and update the URL. In the example case, that would mean adjusting the URL as follows:

https://{tenant}.sharepoint.com/_layouts/15/outlookhostedapp.aspx
  ?componentId=c76ba09e-4068-4233-b342-aedfc75a6578

Notice that the componentId query parameter is a solution-specific GUID, which should be replaced with the value for your own component.

Important

The configuration option is only available during initial view of the add-in. It is not supported to re-configure the add-in after the initial configuration. This is currently by design, as there's no similar configuration capability for the normal Office Add-ins. If there's a demand for this capability, please do let us know using UserVoice.

Deployment of your Add-in

Deployment is a two-step process for the Outlook Web App Add-ins:

  1. Deploy solution to SharePoint App Catalog
  2. Use side loading to activate the add-in in Outlook Web App

You can deploy your solution to the Outlook Web App by using the so-called 'side-loading' technique by following these steps:

  1. Move to the Outlook web client using your browser.

  2. Activate one of the existing mails in your inbox.

  3. Select [...] and choose Get Add-ins:

    Get add-ins context menu

  4. Select My add-ins from the left menu:

    My add-ins left menu

  5. Select Add from file... under the Custom add-ins:

    Add from file

  6. Upload the manifest XML file from your project solution under the officeAddin folder.

  7. Select Install on the warning message to get your add-in available on the tenant

    Warning - Install

  8. Close the add-in window by selecting X in the top-right corner

  9. Activate again the context menu from [...] and select SPFx template to activate the add-in in your inbox (name can be adjusted in the manifest file as needed)

Important

This deployment process is for the preview. The process will change once support is extended to other Office web and desktop applications in the future.