Create a new Teams app

Screenshot shows the Teams Toolkit v4 deprecation note.

In this section, you can learn how to create a new Teams project using Microsoft Visual Studio Code.

Create a new Teams project using Visual Studio Code

You can build a new Teams project by selecting Create a New App in Teams Toolkit. You can start from built-in Teams app templates or start from official Teams app samples in Teams Toolkit. What's more, Teams Toolkit v5 supports to start with Outlook Add-in templates to build your own Outlook Add-ins.

Screenshot shows the App Capability options.

To start with Teams capabilities, you can create the following types of Teams app:

App Types Definition
Scenario-based Teams apps This group of templates are designed for particular abstracted business scenarios that your teams app can serve for. For example notification bot, command bot, SSO-enabled tab, or Dashboard tab app.
Basic Teams apps Basic Teams apps are just hello world Teams tab, bot, or message extension that you can create and customize based on your requirement.
Extend Teams App across Microsoft 365 This group of Teams app can be installed and run on Outlook and Office.com.

Create a new Teams app

The process to create a new Teams app is similar for all types of apps.

To create a basic Teams app:

  1. Open Visual Studio Code.

  2. Select the Teams Toolkit > Create a New App.

    Screenshot shows the Create New Project button in the Teams Toolkit sidebar.

  3. In this example, select Tab as app capability.

    Screenshot shows the App Capability to select.

  4. Select Basic Tab as app capability.

    Screenshot shows to select App Feature using a Tab as Basic Tab.

  5. Select JavaScript as the programming language.

    Screenshot shows the programming language to select.

  6. Select Default folder to store your project root folder in the default location.

    Screenshot shows the default location option to select.

    Learn to change the default folder:
    1. Select Browse.

      Screenshot shows the Browse option highlighted to browse for storage.

    2. Select the location for project workspace.

      Screenshot shows the Select Folder option highlighted.

    The folder you select is the location for your project workspace.

    1. Enter a suitable name for your app, such as helloworld, as the application name. Ensure that you use only alphanumeric characters. Press Enter.

    Screenshot shows where to enter the app name.

    The Teams tab app is created in a few seconds.

    Screenshot shows the app created.

Directory structure for different app types

Teams Toolkit provides all components for building an app. After creating the project, you can view the project folders and files under EXPLORER section.


Directory structure for basic Teams app

The following example shows a basic Teams tab app directory structure:

Folder name Contents
.vscode Settings for VS Code to build and debug your Teams app.
appPackage App manifest (previously called Teams app manifest) file and icon files that Teams used to recognize your Teams app.
env Stores different environment parameters.
infra Azure bicep template files. Used for deploy your Teams app to Azure.
src Source code for the Tab capability, including your front-end app, UI components and the privacy notice, terms of use,
src/app.js Application entry point and restify handlers for website.
src/views/hello.html A HTML template that is bind to the tab endpoint.
src/static The static assets like CSS and JavaScript files that can be served by the web server.
teamsapp.yml This configuration file defines the Teams Toolkit behavior for provision, deploy, and publish lifecycle. You can customize this file to change the behavior of Teams Toolkit in each lifecycle.
teamsapp.local.yml This overrides teamsapp.yml with actions that enable local execution and debugging.

Note

If you have a bot or message extension app, relevant folders are added to the directory structure.

To learn more about the directory structure of different types of basic Teams apps, see the following table:

App Type Links
For tab app Build your first tab app using JavaScript
For bot app Build your first bot app using JavaScript
For message extension app Build your first message extension app using JavaScript

Directory structure for scenario-based Teams app

The following example shows a scenario-based notification bot Teams app directory structure:

The new project folder contains the following content:

Folder name Contents
.vscode Settings for VS Code to build and debug your Teams app.
appPackage The app manifest file and icon files that Teams used to recognized your Teams app.
env Stores different environment parameters.
infra Azure bicep template files. Used for deploy your Teams app to Azure.
teamsapp.yml This configuration file defines the Teams Toolkit behavior for provision, deploy, and publish lifecycle. You can customize this file to change the behavior of Teams Toolkit in each lifecycle.
teamsapp.local.yml This overrides teamsapp.yml with actions that enable local execution and debugging.

The core notification implementation is stored in the src folder and it contains:

File name Contents
src\adaptiveCards\ Templates for Adaptive Card.
src\internal\ Generated initialize code for notification functionality.
src\index.ts The entry point to handle bot messages and send notifications.
.gitignore File to exclude local files from the bot project.
package.json The npm package file for the bot project.

Note

If you have a command bot, workflow bot, SSO-enabled tab, or SPFx tab app, relevant folders are added to the directory structure.

To learn more about the directory structure of different types of scenario-based Teams apps, see the following table:

App Type Links
For notification bot app Send notification to Teams
For command bot app Build command bot
For workflow bot app Create Teams workflow bot
For SPFx tab app Build a Teams app with SPFx

See also

Create a new Teams project for Visual Studio Code

You can build a new Teams project by selecting Create a new Teams app in Teams Toolkit. You can create the following types of apps in Teams Toolkit:

App Types Definition
Basic Teams apps Basic Teams apps are tab, bot, or message extension that you can create and customize based on your requirement.
Scenario-based Teams apps Scenario-based Teams apps are notification bot, command bot, workflow bot, SSO-enabled tab, or SPFx tab app and these are suitable for one particular scenario. For example, a notification bot is suitable to send notifications and not used for chat.

Create a new Teams app

The process to create a new Teams app is similar for all types of apps except SPFx tab app, workflow bot, and notification bot.

To create a basic Teams app:

  1. Open Visual Studio Code.

  2. Select the Teams Toolkit > Create a new Teams app.

    screenshot shows the Create New Project button in the Teams Toolkit sidebar.

  3. Select Start with a Teams capability.

    Screenshot shows the option to select app type.

  4. Ensure that Tab is selected as app capability.

    Select App Capability

  5. Select JavaScript as the programming language.

    Screenshot showing how to select the programming language.

  6. Select Default folder to store your project root folder in the default location.

    Select default location

    Learn to change the default folder:
    1. Select Browse.

      Select browse for storage

    2. Select the location for project workspace.

      select-folder for storage

    The folder you select is the location for your project workspace.

  7. Enter a suitable name for your app, such as helloworld, as the application name. Ensure that you use only alphanumeric characters. Press Enter.

    Screenshot showing where to enter the app name.

    By default, your app project opens in a new window. You can open your app project in the current window as well.

    New window notification

    The Teams tab app is created in a few seconds.

    Screenshot showing the app created.

Directory structure for different app types

Teams Toolkit provides all components for building an app. After creating the project, you can view the project folders and files under EXPLORER section.


Directory structure for basic Teams app

The following example shows a basic Teams tab app directory structure:

Folder name Contents
.fx\configs Configuration files that you can customize for the Teams app.
- .fx\configs\azure.parameters.<envName>.json Parameters file for Azure bicep provision for every environment.
- .fx\configs\config.<envName>.json Configuration file for every environment.
- .fx\configs\projectSettings.json Global project settings that apply to all environments.
tabs Code for the Tab capability needed at runtime, such as the privacy notice, terms of use, and configuration tabs.
- tabs\src\index.jsx Entry point for the front-end app, where the main app component is rendered with ReactDOM.render().
- tabs\src\components\App.jsx Code for handling URL routing in the app. It calls the Microsoft Teams JavaScript client library to establish communication between your app and Teams.
- tabs\src\components\Tab.jsx Code to implement the UI of your app.
- tabs\src\components\TabConfig.jsx Code to implement the UI that configures your app.
templates\appPackage App manifest template files, and the app icons: color.png and outline.png.
- templates\appPackage\manifest.template.json App manifest for running the app in local or remote environment.
templates\azure bicep template files.

Note

If you have a bot or message extension app, relevant folders are added to the directory structure.

To learn more about the directory structure of different types of basic Teams apps, see the following table:

App Type Links
For tab app Build your first tab app using JavaScript
For bot app Build your first bot app using JavaScript
For message extension app Build your first message extension app using JavaScript

Directory structure for scenario-based Teams app

The following example shows a scenario-based notification bot Teams app directory structure:

The new project folder contains the following content:

Folder name Contents
.fx Project level settings, configuration, and environment information.
.vscode VS code files for local debug.
bot The bot source code.
templates Templates for app manifest and corresponding Azure resources.

The core notification implementation is stored in the bot folder, and it contains:

File name Contents
src\adaptiveCards\ Templates for Adaptive Card.
src\internal\ Generated initialize code for notification functionality.
src\index.ts The entry point to handle bot messages and send notifications.
.gitignore File to exclude local files from the bot project.
package.json The npm package file for the bot project.

Note

If you have a command bot, workflow bot, SSO-enabled tab, or SPFx tab app, relevant folders are added to the directory structure.

To learn more about the directory structure of different types of scenario-based Teams apps, see the following table:

App Type Links
For notification bot app Send notification to Teams
For command bot app Build command bot
For workflow bot app Create Teams workflow bot
For SPFx tab app Build a Teams app with SPFx

Directory structure for multi-capability app

You can add more features to your existing Teams app by using Add features. For example, if you add a bot app to the existing tab app, Teams Toolkit adds the bot folder with relevant files and code.

The following image shows the directory structure of a tab app:

Tab app directory structure

The following image shows the directory structure of tab app with bot feature:

Tab app with bot app directory structure

See also