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:

  1. Open Visual Studio code.

  2. Open the Teams Toolkit and select the Teams icon in the sidebar:

    The Teams Icon in the Visual Studio Code sidebar.

  3. Select Create New Project.

    Location of the Create New Project link in the Teams Toolkit sidebar.

  4. Select Create a new Teams app.

    Wizard start for Create New Project

  5. In the Select capabilities section, verify that Tab is selected and select OK.

    Screenshot showing how to add capabilities to your new app.

  6. In the Frontend hosting type section, select Azure.

    Screenshot showing how to select hosting for your new app.

  7. In the Cloud resources section, select OK. We do not need additional cloud resources for this tutorial.

    Screenshot showing how to add cloud resources for your new app.

  8. In the Programming Language section, select JavaScript.

    Screenshot showing how to select the programming language.

  9. Select a workspace folder. A folder is created within your workspace folder for the project you are creating.

  10. 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.

Screenshot showing app project files for a personal app in 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.

  • The settings you chose when creating the project are stored in .fx/settings.json.
  • The state of your project is stored in .fx/env.*.json.

And the Teams app information is stored in the appPackage directory.

  • The app icons are stored as PNG files in appPackage/color.png and appPackage/outline.png.
  • The app manifest for publishing to Developer Portal for Teams is stored in appPackage/manifest.source.json.

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.jsx is the front-end app's entry point, where the main App component is rendered with ReactDOM.render().
  • tabs/src/components/App.jsx handles URL routing in your app. It calls the Microsoft Teams JavaScript client SDK to establish communication between your app and Teams.
  • tabs/src/components/Tab.jsx contains the code to implement the UI of your app.
  • tabs/src/components/TabConfig.jsx contains the code to implement the UI that configures your app.

Several tabs are required by the Teams runtime, including the privacy notice, terms of use, and configuration tabs. The code for the privacy notice and terms of use are located in the same directory.

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 https://localhost:5000.
  • The HTML, CSS, and JavaScript resources that make up the front end of the app are hosted on a local service. It can be accessed at https://localhost:3000.
  • 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.

After this is done, the app can be loaded within the Teams client. We use the Teams web client so that we can see the HTML, CSS, and JavaScript code within a standard web development environment.

Build and run your app locally in Visual Studio Code

To build and run your app locally:

  1. 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. Screenshot showing how the prompt to install a SSL certificate to enable Teams to load your application from localhost.

    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:

    Screenshot showing how the prompt to install a SSL certificate to enable Teams to load your application from localhost.

  2. 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.

    Screenshot showing how to pick the web version of teams when launched

  3. Sign in with your M365 account when prompted.

  4. When prompted to install the app onto Teams, press Add.

Your app is now displayed:

Screenshot of the completed app

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.

  1. Open Visual Studio Code.

  2. Select the Teams Toolkit from the sidebar by selecting the Teams icon.

  3. Select Provision in the Cloud.

    Screenshot showing the provisioning commands

  4. If required, select a subscription to use for the Azure resources.


    There are always some Azure resources used for hosting your app.

  5. A dialog warns you that costs may be incurred when running resources in Azure. Press Provision.

    Screenshot of the provisioning dialog.

    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:

    Screenshot showing the provisioning complete dialog.

  6. 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?

The Provision step creates resources in Azure and M365 for your app, but no code (HTML, CSS, JavaScript, etc.) is copied to the resources. The Deploy step copies the code for your app to the resources you created during the provision step. It is common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it is separate from the deployment step.

Once the provisioning and deployment steps are finished:

  1. From Visual Studio Code, open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run)
  2. Select Launch Remote (Edge) from the launch configuration drop-down.
  3. 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.

See also