|
| 1 | +--- |
| 2 | +title: Extend Outlook and Office with the SharePoint Framework |
| 3 | +description: Learn how you can use the SharePoint Framework to create apps for Microsoft 365, including Microsoft Teams, Outlook, and Office clients |
| 4 | +ms.date: 11/14/2022 |
| 5 | +ms.localizationpriority: high |
| 6 | +--- |
| 7 | +# Extend Outlook and Office with the SharePoint Framework |
| 8 | + |
| 9 | +[!INCLUDE [spfx-release-beta](../../../includes/snippets/spfx-release-beta.md)] |
| 10 | + |
| 11 | +The SharePoint Framework (SPFx) v1.16 release added support for the [Microsoft Teams JavaScript client SDK v2](/javascript/api/overview/msteams-client). The Microsoft Teams JavaScript client SDK v2 introduced the ability to enable [Teams apps to run in Outlook at Office, in addition to Microsoft Teams](/microsoftteams/platform/m365-apps/overview). |
| 12 | + |
| 13 | +With this improvement in SPFx v1.16, developers can now use the SPFx to create apps for Outlook and Office using the [existing support for creating apps for Microsoft Teams](/sharepoint/dev/spfx/build-for-teams-overview). |
| 14 | + |
| 15 | +> [!IMPORTANT] |
| 16 | +> The ability to run Microsoft Teams apps in Outlook and Office is currently in beta with anticipated availability in the first half of calendar year 2023. |
| 17 | +
|
| 18 | +> [!IMPORTANT] |
| 19 | +> Essential information required for user success |
| 20 | +> |
| 21 | +> To test using Microsoft Teams apps in Outlook and Office, including those created with the SPFx, you must configure your Microsoft 365 tenant's release preferences for *targetted release*. For more information on changing your organizations release preferences, see [Set up the Standard or Targeted release options](/microsoft-365/admin/manage/release-options-in-office-365). |
| 22 | +> |
| 23 | +> It takes 5 business days for your tenant's release preferences to take effect. In other words, change your tenant from the **standard release** track to the **target release** track on the 5th of the month, you won't be able to test your Microsoft Teams apps created with the SPFx in Outlook or Office until the 11th of the month. |
| 24 | +
|
| 25 | +## Create Microsoft Teams apps for Outlook and Office |
| 26 | + |
| 27 | +To create a new Microsoft Teams app with SPFx for Outlook and Office, you start by first creating a new SPFx project using the Yeoman generator for SharePoint v1.16 or later the same way you'd create a new web part. For more information, see [Build your first SharePoint client-side web part](../web-parts/get-started/build-a-hello-world-web-part.md). |
| 28 | + |
| 29 | +The Yeoman SharePoint Generator will prompt you with a series of questions. Follow the same guidance for creating a new SPFx web part when responding to these questions. |
| 30 | + |
| 31 | +Once the project has been created, update the web part's `supportedHosts` property to indicate where it can be used. For example, add `TeamsTab` and/or `TeamsPersonalApp` to te `supportedHosts` property in the **./config/package-solution.json** file. For more information, see [Building Microsoft Teams Tabs using SharePoint Framework](../integrate-with-teams-introduction.md). |
| 32 | + |
| 33 | +## Determine the current runtime host for your app |
| 34 | + |
| 35 | +Your application may need to determine where it's currently running for various reasons. For example, should users see one experience if it's running in SharePoint, Microsoft Teams, Outlook, or another Office client? |
| 36 | + |
| 37 | +Use the SPFx's `context` property on the web part's class and the Microsoft Teams JavaScript client to determine the hosting client. The `app.host.name` property on the Teams JavaScript client contains the name of the host if it's Microsoft Teams, Outlook, or Office. If the Microsoft Teams context object is `undefined`, then the web part is running in SharePoint. |
| 38 | + |
| 39 | +```typescript |
| 40 | +// if running in Microsoft Teams, Outlook, or Office... |
| 41 | +if (!!this.context.sdks.microsoftTeams) { |
| 42 | + const teamsContext = await this.context.sdks.microsoftTeams.teamsJs.app.getContext(); |
| 43 | + switch (teamsContext.app.host.name.toLowerCase()) { |
| 44 | + case 'teams': |
| 45 | + // RUNNING IN MICROSOFT TEAMS |
| 46 | + case 'office': |
| 47 | + // RUNNING IN OFFICE / OFFICE.COM |
| 48 | + case 'outlook': |
| 49 | + // RUNNING IN OUTLOOK |
| 50 | + default: |
| 51 | + throw new Error('Unknown host'); |
| 52 | + } |
| 53 | +} else { |
| 54 | + // RUNNING IN SHAREPOINT |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +## Create the Microsoft Teams app manifest & package |
| 59 | + |
| 60 | +While the SharePoint Online App Catalog's **Sync to Teams** button can automatically create the Microsoft Teams app manifest, app package and install it in the Microsoft Teams store, this currently doesn't support the required Microsoft Teams app manifest file format. The Teams app manifest file must be v1.13 or later |
| 61 | + |
| 62 | +The other option is to manually create the app manifest and app package yourself and include them in the SharePoint package uploaded to the App Catalog. When you select the **Sync To Teams** button in the App Catalog, SharePoint Online will use the Teams app package you created and have included in the SharePoint package. |
| 63 | + |
| 64 | +> [!NOTE] |
| 65 | +> For more information on manually creating Microsoft Teams app manifests and app packages, see [Deployment options for SharePoint Framework solutions for Microsoft Teams](../deployment-spfx-teams-solutions.md) |
| 66 | +
|
| 67 | +### Create the Microsoft Teams app manifest |
| 68 | + |
| 69 | +The first step is to create the Microsoft Teams app manifest. |
| 70 | + |
| 71 | +1. Create the following file in your SPFx project: **./teams/manifest.json**. |
| 72 | +1. Follow the guidance in [Microsoft Teams: App manifest schema for Teams](/microsoftteams/platform/resources/schema/manifest-schema) and [SharePoint Framework: Deployment options for SharePoint Framework solutions for Microsoft Teams](../deployment-spfx-teams-solutions.md) to create a new app manifest file. |
| 73 | +1. Take special note of the following properties in the **manifest.json** file: |
| 74 | + - `manifestVersion`: This must be set to **1.13** or higher |
| 75 | + - `staticTabs` and/or `configurableTabs`: Verify this follows the guidance for using a SPFx web part as a Microsoft Teams tab. |
| 76 | + |
| 77 | + For example, the `contentUrl` property, and any other property that references SPFx components, should use the dynamic tokens `{teamSiteDomain}`, `{teamSitePath}`, & `{locale}`. It should also reference the SPFx's component ID. |
| 78 | + |
| 79 | + > [!TIP] |
| 80 | + > For more information on these properties, see [SharePoint Framework: Deployment options for SharePoint Framework solutions for Microsoft Teams](../deployment-spfx-teams-solutions.md), specifically the section on **Dynamically reference the underlying SharePoint site URLs**. |
| 81 | +
|
| 82 | +> [!NOTE] |
| 83 | +> To learn more about the Microsoft Teams app manifest file, see [Microsoft Teams: App manifest schema for Teams](/microsoftteams/platform/resources/schema/manifest-schema). |
| 84 | +
|
| 85 | +### Create the Microsoft Teams app package |
| 86 | + |
| 87 | +Once you've created the Microsoft Teams app manifest, you need to manually create the app package. This will be included in your SharePoint package (**\*.sppkg**) file that you'll upload to your SharePoint tenant's App Catalog. |
| 88 | + |
| 89 | +1. Compress the contents of the **./teams** folder in your project. |
| 90 | +1. Rename the ZIP package to **TeamsSPFxApp.zip**. |
| 91 | + |
| 92 | +> [!IMPORTANT] |
| 93 | +> The Microsoft Teams app package must be named **TeamsSPFxApp.zip** and saved in the **./teams** folder for this option to work with the **Sync to Teams** button in the tenant's App Catalog. |
| 94 | +
|
| 95 | +## Deploy the SPFx based Microsoft Teams app |
| 96 | + |
| 97 | +Once you've created the app package, the next step is to deploy and install it. |
| 98 | + |
| 99 | +Deploy the app to your tenant's app catalog. |
| 100 | + |
| 101 | +Then, select the app, select the **Files** tab from the ribbon, and then select the **Sync to Teams** button to deploy the app package to your tenant's Microsoft Teams store. |
| 102 | + |
| 103 | +> [!NOTE] |
| 104 | +> For more information on packaging & deploying SharePoint packages to the Microsoft Teams App Store, see **[SharePoint Framework: Deployment options for SharePoint Framework solutions for Microsoft Teams](../deployment-spfx-teams-solutions.md)**. |
| 105 | +
|
| 106 | +Now that you've deployed the app to SharePoint, you can add it as a web part to a page in your SharePoint sites: |
| 107 | + |
| 108 | + |
| 109 | + |
| 110 | +The app can also be installed in Microsoft Teams. Once you're logged in, select the **Apps** option in the left vertical navigation. |
| 111 | + |
| 112 | +Notice your apps are listed under the **Build for your org** section: |
| 113 | + |
| 114 | + |
| 115 | + |
| 116 | +Once you install the app, it will appear in the left vertical navigation as a pinned app: |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | + |
| 121 | + |
| 122 | +You can follow the same process to install the app in Outlook as you performed in Microsoft Teams. |
| 123 | + |
| 124 | +> [!TIP] |
| 125 | +> For more information, see the **[React Teams Lead Dashboard](https://github.com/pnp/sp-dev-fx-webparts/tree/main/samples/react-teams-lead-dashboard)** sample for a working example that uses the SPFx to create a Microsoft Teams app for Outlook and Office. |
0 commit comments