Build apps with the Teams Toolkit and Visual Studio Code

The Teams Toolkit for Visual Studio Code helps developers create and deploy Teams apps with integrated identity, access to cloud storage, data from Microsoft Graph, and other services in Azure and Microsoft 365 with a “zero-configuration” approach to the developer experience.

You also can use the toolkit with Visual Studio or as a CLI (called teamsfx).

Install the Teams Toolkit for Visual Studio Code

  1. Open Visual Studio Code.
  2. Select the Extensions view (Ctrl+Shift+X / ⌘⇧-X or View > Extensions).
  3. In the search box, enter Teams Toolkit.
  4. Select on the green install button next to the Teams Toolkit.

You also can find the Teams Toolkit on the Visual Studio Code Marketplace.

The following tools are installed by the Visual Studio Code extension when they're needed. If already installed, the installed version is used instead. If using Linux (including WSL), you must install these tools before use:

  • Azure Functions Core Tools

    Azure Functions Core Tools is used to run any backend components locally during a local debug run, including the authentication helpers required when running your services in Azure. It's installed within the project directory using the npm devDependencies.

  • .NET SDK

    The .NET SDK is used to install customized bindings for local debugging and Azure Functions app deployments. If you haven't installed the .NET 3.1 or later SDK globally, the portable version is installed.

  • ngrok

    Some Teams app features (conversational bots, messaging extensions, and incoming webhooks) require inbound connections. You need to expose your development system to Teams through a tunnel. A tunnel isn't required for apps that only include tabs. This package is installed within the project directory (using npm devDependencies).

Use the Teams Toolkit for Visual Studio Code

Set up a new Teams project

The Teams Toolkit can create React apps that are hosted in Azure or SPFx web parts that are hosted on your Microsoft 365 SharePoint environment. To create a new React app to be hosted on Azure:

  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 is already selected. You can also optionally select Bot and Messaging Extension. Press OK.

    Screenshot showing how to add capabilities to your new app.

  6. On the Frontend hosting type step, select Azure.

    Screenshot showing how to select hosting for your new app.

  7. Optionally, on the Cloud resources step, select cloud resources that your application uses. You can select CRUD (create, read, update, and delete) access to a SQL table or an API:

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

  8. On the Programming Language step, you can choose JavaScript or TypeScript:

    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're 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. The scaffolded app contains code to handle single sign-on with Azure Active Directory and access to the Microsoft Graph. If you selected Azure resources, then the code for those resources is also available.

For a walk-through of the SPFx creation and publication process, see the SPFx tutorial.

Configure your app

At its core, the Teams app embraces three components:

  1. The Microsoft Teams client (web, desktop or mobile) where users interact with your app.

  2. A server that responds to requests for content that is displayed in Teams. For example, HTML tab content or a bot Adaptive Card.

  3. A Teams app package consists of three files:

    • The manifest.json.
    • A color icon for your app to display in the public or organization app catalog.
    • An outline icon for display on the Teams activity bar.

The manifest and icons are stored in the .fx folder of your project prior to being uploaded to Teams. When an app is installed, the Teams client parses the manifest file to determine needed information like the name of your app and the URL where the services are located.

  1. To configure your app, navigate to the Teams Toolkit tab in Visual Studio Code.
  2. Select Manifest Editor in the Project section.

Editing the fields in the App details page updates the contents of the manifest.json file that is ultimately shipped as part of the app package.

Install and run your app locally

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.

    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 is started to run the application. If prompted to open Microsoft Teams, select Cancel to remain within the browser. You may also be prompted to switch to the Teams application at other times. Select the web app when this happens.

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

  3. You may be prompted to sign in. If so, sign in with your Microsoft 365 account.

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

Both the backend and frontend are hooked into the Visual Studio Code debugger. This allows you to set breakpoints anywhere in your code and inspect state. You can also use any frontend debugging tools (such as the React Developer Tools) within the browser. For more information about debugging in Visual Studio Code, review the documentation.

Publish your app to Teams

Before it can be used by other people, you must publish your app to the Developer Portal for Teams.

  1. To publish your app, navigate to the Teams Toolkit tab in Visual Studio Code.
  2. Select Publish to Teams in the Project section.

If using Azure hosting, you must have provisioned and deployed to the cloud. For a walk-through of the SPFx publication process, see the SPFx tutorial.

Next step

See also