Edit

Share via

Deployment options for SharePoint Framework solutions for Microsoft Teams

  • Article

Developers have multiple options when deploying SharePoint Framework (SPFx) solutions for use within Microsoft Teams. This article explains the options supported in SharePoint Online.

Note

Prior to January 2021, SharePoint Online only supported one option: when a qualifying SPFx solution was uploaded to the SharePoint tenant app catalog, the Sync To Teams button in the tenant app catalog's ribbon.

SharePoint Online supports two options for deploying SPFx solutions to the Microsoft Teams app store:

  1. Automatically create the Microsoft Teams app manifest and package
  2. Use the developer-provided Microsoft Teams app manifest & package

Automatically create the Microsoft Teams app manifest and package

This capability is ideal when you have a simple implementation to expose automatically in Microsoft Teams.

In this scenario, when an SPFx solution is uploaded to the SharePoint Online tenant app catalog, if the solution contains components for Microsoft Teams, the Add to Teams button in the ribbon is enabled.

Add to Teams

This button will start the following process in SharePoint Online:

  1. SharePoint will dynamically create the Microsoft Teams app manifest file
  2. SharePoint will dynamically create the Microsoft Teams app package
  3. SharePoint will deploy the generated Microsoft Teams app package to the tenant's Microsoft Teams app store

When SharePoint creates the app manifest, it will use values from the SPFx solution in generating some names. The following table lists the properties in the Microsoft Teams app manifest file and what values they are set to.

Note

Refer to the following link in the Microsoft Teams documentation for more detail on the app manifest: Manifest schema for Microsoft Teams.

manifest.json property Property in SPFx component manifest
packageName alias
id id
name.short preconfiguredEntries[0].title
description.short preconfiguredEntries[0].description
description.long preconfiguredEntries[0].description

Note

The component manifest is pulled from the component's manifest (./src/webparts/../*.manifest.json).

If a SPFx solution contains multiple web parts designated for use in Microsoft Teams, SharePoint Online will repeat the above process for each of them.

Note

If you are curious on the generated package structure, you can use use the following REST API to download the package for specific solutions:

_api/web/tenantappcatalog/downloadteamssolution(id)/$value

id is the numeric identifier of the solution in the app catalog library.

You can request this API in the context of your app catalog, for example with URL of https://[yourtenant]].sharepoint.com/sites/appcatalog/_api/web/tenantappcatalog/downloadteamssolution(12)/$value. API call will start download process of the generated manifest package.

Developer-provided Microsoft Teams app manifest & package

When you need more control over the Microsoft Teams app manifest or app package, you can create your own package. In this case, when an administrator selects the Sync to Teams button, SharePoint Online will look for the following file in the *.sppkg file: ./teams/TeamsSPFxApp.zip.

If this file is present, SharePoint Online will deploy it to the tenant's Microsoft Teams app store instead of dynamically creating it. This option gives developers full control over the Microsoft Teams app manifest & app package.

This option is ideal for the following scenarios:

  • Developers want to have full control over the Microsoft Teams app manifest contents
  • Complex Microsoft Teams scenarios, like specifying bots, meeting apps, etc
  • Specify the ID, name & description of the Microsoft Teams app when the SPFx solution contains more than one component. For example, if a SPFx solution contains multiple web parts that can be used as tabs in Microsoft Teams, the automatic generation of the manifest will select one of the two components to use as the Microsoft Teams' app ID, name & description.

To use your own Microsoft Teams app manifest & app package instead of letting SharePoint Online dynamically create it, do the following:

  1. Create a Microsoft Teams app manifest per the Microsoft Teams documentation:

    Important

    in the Teams app manifest ensure you add the following entry:

    "webApplicationInfo": {
"resource": "https://{teamSiteDomain}",
"id": "00000003-0000-0ff1-ce00-000000000000"
}

    That is required to ensure any API call in the component will succeed from Microsoft Teams rich clients. teamSiteDomain will be the same tenant that the Teams client is using, this will not work cross-tenant/cross-domain so you cannot hardcode another domain in.

  2. Create the Microsoft Teams app package named TeamsSPFxApp.zip by compressing the contents of the ./teams folder.

    Important

    Don't compress the folder, instead compress the contents of the folder. If you ZIP the folder, it will a top-level subfolder to the resulting ZIP file which isn't a valid app package in Microsoft Teams.

  3. Save the TeamsSPFxApp.zip in the SPFx solution's ./teams folder.

  4. Create the SPFx package the same way you would with a regular SPFx solution, using gulp package-solution. It will include the custom Microsoft Teams app package in the *.sppkg.

Dynamically reference the underlying SharePoint site URLs

The Microsoft Teams app manifest must point to the deployed hosting location of the SPFx components. However, these URLs are not known at the time the Microsoft Teams app manifest or app package is created.

Therefore, when you specify the app package in this deployment option, you should use the following strings that will be replaced at runtime by Microsoft Teams:

  • {teamSiteDomain}: the SharePoint Online tenant URL where the SPFx solution is deployed and installed
  • {teamSitePath}: the path to the SharePoint site where the SPFx components were installed
  • {locale}: the current locale of the Microsoft Teams client

When using a web part in a custom Microsoft Teams solution, you can use these strings to define the URL of the page that will load the web part. For example, use the following table as a guide for creating the URL of web parts used in Microsoft Teams apps:

Important

In the following examples, it's assumed the SPFx component's ID is {{SPFX_COMPONENT_ID}}. Make sure to replace this value with the component ID for your web part. This value is not dynamically set by SharePoint or Microsoft Teams: it is the developer's responsibility to set this value.

Microsoft Teams component Microsoft Teams app manifest property Microsoft Teams app manifest property
Personal tab staticTabs[..].contentUrl https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamshostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Channel/group chat tab configurableTabs[..].configurationUrl https://{teamSiteDomain}{teamSitePath}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest={teamSitePath}/_layouts/15/teamshostedapp.aspx%3FopenPropertyPane=true%26teams%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Messaging extension composeExtensions.commands[..].taskInfo.url https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamstaskhostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}