Build and run your first Microsoft Teams app with React
In this tutorial, you will learn how to 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 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 and select the Teams icon in the sidebar:
Select Create New Project.
Select Create a new Teams app.
In the Select capabilities section, verify that Tab is selected and select OK.
In the Frontend hosting type section, select Azure.
In the Cloud resources section, select 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.
After 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
- The settings you chose when creating the project are stored in
- The state of your project is stored in
And the Teams app information is stored in the
- The app icons are stored as PNG files in
- The app manifest for publishing to Developer Portal for Teams is 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. 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.
For the first time to run locally, you will be prompted to install a certificate for local debug. click Continue.
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.
Sign in with your M365 account when prompted.
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 press the F5 key, the Teams Toolkit:
- Registers your application with Azure Active Directory.
- Sideloads your app in Teams.
- Starts your application backend running locally using Azure Function Core Tools.
- Starts your application front-end hosted locally.
- Starts 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.