Build and run your first Microsoft Teams app with React
In this tutorial, you will create a new Microsoft Teams app in React that implements a simple personal app to pull information from the Microsoft Graph. For example, a personal app includes a set of tabs scoped for individual use. During the tutorial, you will learn about the structure of a Teams app, how to run an app locally, and how to deploy the app to Azure.
The app that is built displays basic user information for the current user. When permission is granted, the app will connect to the Microsoft Graph as the current user to get the complete profile.
Before you begin
Make sure your development environment is set up by installing the prerequisites.
Create your project
Use the Teams Toolkit to create your first project:
Open Visual Studio code.
Open the Teams Toolkit by selecting the Teams icon in the sidebar:
Select Create New Project.
Select Create a new Teams app.
On the Select capabilities step, the Tab capability is already selected. Press OK.
On the Frontend hosting type step, select Azure.
On the Cloud resources step, press OK. We do not need additional cloud resources for this tutorial.
Select a workspace folder. A folder is created within your workspace folder for the project you are creating.
Enter a suitable name for your app, like
helloworld. The name of the app must consist only of alphanumeric characters. Press Enter to continue.
Your Teams app is created within a few seconds.
Take a tour of the source code
If you wish to skip this section for now, you can run your app locally.
Once the Teams Toolkit configures your project, you have the components to build a basic personal app for Teams. The project directories and files display in the Explorer area of Visual Studio Code.
The Toolkit automatically creates scaffolding for you in the project directory based on the capabilities you added during setup. The Teams Toolkit maintains its state for your app in the
.fx directory. Among other items in this directory:
- The app icons are stored as PNG files in
- The app manifest for publishing to the Developer Portal for Teams is stored in
- The settings you chose when creating the project are stored in
Since you selected the tab capability during setup, the Teams Toolkit scaffolds all the necessary code for a basic tab in the
tabs directory. Within this directory there are several important files:
tabs/src/index.jsxis the front-end app's entry point, where the main
Appcomponent is rendered with
tabs/src/components/Tab.jsxcontains the code to implement the UI of your app.
tabs/src/components/TabConfig.jsxcontains the code to implement the UI that configures your app.
When you add cloud functionality, additional directories are added to the project. Most notably, the
api directory holds the code to any Azure Functions you write.
Run your app locally
Teams Toolkit allows you to run your app locally. This consists of several parts that are necessary to provide the correct infrastructure that Teams expects:
- An application is registered with Azure Active Directory. This application has permissions associated with the location that the app is loaded from and any backend resources it accesses.
- A web API is hosted to assist with authentication tasks, acting as a proxy between the app and Azure Active Directory. This is run by Azure Functions Core Tools. It can be accessed at the URL
- An app manifest is generated and exists in the Developer Portal for Teams. Teams uses the app manifest to tell connected clients where to load the app from.
Build and run your app locally in Visual Studio Code
To build and run your app locally:
From Visual Studio Code, press F5 to run your application in debug mode.
When you run the app for the first time, all dependencies are downloaded and the app is built. A browser window automatically opens when the build is complete. This can take 3-5 minutes to complete.
The Toolkit prompts you to install a local certificate if required. This certificate allows Teams to load your application from
https://localhost. Select yes when the following dialog appears:
Your web browser starts to run the app. If prompted to open Teams desktop, select Cancel to remain in the browser. You may also be prompted to switch to Teams desktop at other times; select the Teams web app when this happens.
You may be prompted to sign in. If so, sign in with your M365 account.
When prompted to install the app onto Teams, press Add.
Your app is now displayed:
You can do normal debugging activities as if this were any other web application, such as setting breakpoints. The app supports hot reloading. If you change any file within the project, the page will be reloaded.
Learn what happens when you run your app locally in the debugger.
When you pressed F5, the Teams Toolkit:
- Registered your application with Azure Active Directory.
- Sideloaded your app in Teams.
- Started your application backend running locally using Azure Function Core Tools.
- Started your application front-end hosted locally.
- Started Microsoft Teams in a web browser with a command to instruct Teams to side load the application from
https://localhost:3000/tab. This is the URL registered in the application manifest.
Learn how to troubleshoot common issues when running your app locally.
To successfully run your app in Teams, you must have a Teams account that allows app sideloading. For more information on account opening, see prerequisites.
Deploy your app to Azure
Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning), then the code that makes up your app is copied into the created cloud resources.
Open Visual Studio Code.
Select the Teams Toolkit from the sidebar by selecting the Teams icon.
Select Provision in the Cloud.
If required, select a subscription to use for the Azure resources.
There are always some Azure resources used for hosting your app.
A dialog warns you that costs may be incurred when running resources in Azure. Press Provision.
The provisioning process creates resources in the Azure cloud. This takes some time. You can monitor the progress by watching the dialogs in the bottom right corner. After a few minutes, you see the following notice:
Once provisioning is complete, select Deploy to the Cloud. As with provisioning, this process takes some time. You can monitor the process by watching the dialogs in the bottom right corner. After a few minutes, you see a completion notice.
What's the difference between Provision and Deploy?
Once the provisioning and deployment steps are finished:
- From Visual Studio Code, open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run)
- Select Launch Remote (Edge) from the launch configuration drop-down.
- Press the Play button to launch your app - now running remotely from Azure!
Learn what happens when you deployed your app to Azure
Before deployment, the application has been running locally:
- The backend runs using Azure Functions Core Tools.
- The application HTTP endpoint, where Microsoft Teams loads the application, runs locally.
Deployment involves provisioning resources on an active Azure subscription and deploying or uploading the backend and frontend code for the application to Azure.
- The backend if configured uses a variety of Azure services, including Azure App Service and Azure Storage.
- The frontend application will be deployed to an Azure Storage account configured for static web hosting.
- Create a Teams app with Blazor
- Create a Teams app as a SharePoint Web Part (Azure not required)
- Create a conversational bot app
- Create a messaging extension