Build and run your first Microsoft Teams app with SharePoint Framework (SPFx)

In this tutorial, you will create a new Microsoft Teams app in SharePoint Framework (SPFx) that implements a simple personal app. (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 the app locally, and how to deploy the app to SharePoint.

Before you begin

Make sure your development environment is set up by installing the prerequisites

Get organized

In addition to the prerequisites, you also need to be an Administrator for a SharePoint Site Collection. This is where you will deploy your app for hosting. If you are using an M365 developer program tenant, use the administrator account you set up when you registered for the program.

Create your project

Use the Teams Toolkit to create your first project:

  1. Open Visual Studio code.

  2. Open the Teams Toolkit by selecting 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. On the Select capabilities step, the Tab capability will already be selected. Press OK.

    Screenshot showing how to add capabilities to your new app.

  6. On the Frontend hosting type step, select SharePoint Framework (SPFx).

    Screenshot showing how to select hosting for your new app.

  7. On the Framework step, select React.

    Select Framework

  8. When asked for a Webpart Name, press Enter to accept the default.

  9. When asked for the Webpart Description, press Enter to accept the default.

  10. When asked for the Programming Language, press Enter to accept the default.

  11. Select a workspace folder. A folder will be created within your workspace folder for the project you are creating.

  12. 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 will be 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 that is hosted within the SharePoint Framework. 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. Among other items in this directory:

  • The app icons are stored as PNG files in color.png and outline.png.
  • The app manifest for publishing to Developer Portal for Teams is stored in manifest.source.json.
  • The settings you chose when creating the project are stored in settings.json.

Since you selected an SPFx Webpart project, the following files are relevant to your UI:

  • The folder SPFx/src/webparts/{webpart} contains your SPFx webpart.
  • The file .vscode/launch.json describes the debugging configurations available in the debug palette.

For more information about SharePoint Webparts for Teams, refer to the SharePoint documentation.

Run your app locally

Teams Toolkit allows you to host your app locally and run it through the SharePoint Framework Workbench.

Build and run your app locally in Visual Studio Code

To build and run your app locally:

  1. From Visual Studio Code, press F5.

    Screenshot showing how to start an SPFx app in a local workbench.


    When you run the app for the first time, all dependencies are downloaded and the app is built. A browser window automatically opens and loads the SharePoint Workbench when the build is complete. This can take 3-5 minutes to complete.

    Once the SharePoint Workbench is loaded.


    The Toolkit will prompt you to install a local certificate if needed. 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. Press one of the Add Webpart (+) icons to add your webpart.

    Screenshot showing the SPFx workbench running with the popup to add a webpart showing.

  3. Choose your webpart from the menu.

    Screenshot showing the SPFx workbench running with the popup to add a webpart selection.

Your app should now be running. You can do normal debugging activities as if this were any other SPFx webpart (such as setting breakpoints).


Try placing breakpoints in the render method of SPFx/src/webparts/{webpart}/{webpart}.ts and reloading the browser window. VS Code will stop on breakpoints in your code.

Deploy your app to SharePoint

Ensure a SharePoint App Catalog exists in your deployment. If one does not exist, create one. It may take up to 15 minutes for the app catalog to be fully created.

  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. You can monitor the progress by watching the dialogs in the bottom right corner. After a few seconds, you will see the following notice:

    Screenshot showing the provisioning complete dialog.

  5. Once provisioning is complete, select Deploy to the cloud.

  6. Currently, automated deployment is not available. A dialog will pop up prompting you to build and deploy manually. Press Build SharePoint Package.

    Screenshot for the Build Sharepoint Package dialog

The SharePoint package is located in SPFx/sharepoint/solution within your project. Upload the package to SharePoint:

  1. Log into the M365 Admin Console, then navigate to the SharePoint App Catalog.

    • Open
    • Under Admin centers, select the SharePoint admin center.
    • Select More features from the sidebar menu.
    • Press Open under Apps.
    • Select App Catalog.
  2. Select Distribute apps for SharePoint.

    Distribute apps for SharePoint.

  3. Select Upload.

  4. Press Choose File.

  5. Locate your {project}.sppkg file, located in the SPFx/sharepoint/solution folder within your project. Press Open.

  6. Press OK.

  7. The SharePoint deployment process will automatically start. Ensure Make this solution available to all sites in the organization is checked, then press Deploy.

  8. Select the FILES tab.

    Select the files tab in the SharePoint App Catalog.

  9. select the package you deployed, then press Sync to Teams in the ribbon.


    The Sync to Teams process can take a couple of minutes. You will see a message on the right-hand side of the browser indicating that the app has successfully synchronized to Teams.

Open the Teams application (or sign in at Press the triple-dot on the sidebar, then select All apps. The app will be placed in the Apps built for your org category. You can add the app from there.

Screenshot showing the app within Teams

Next steps

Learn about other methods for creating Teams apps: