Build your first tab app using JavaScript
Start Microsoft Teams app development with your first Teams app. You can create a tab app with Teams.
Your app will have a capability, which comes with its own UI and UX:
Note
In this tutorial, you can create a tab app with JavaScript.
In this tutorial, you learn:
- How to set up a new project with Teams Toolkit.
- How to build a tab app.
- The structure of the app:
- The tab portion with JavaScript using React.
- The rest of the features with Node.js.
- How to deploy your app.
Prerequisites
Here's a list of tools you need for building and deploying your apps.
| Install | For using... | |
|---|---|---|
| Required | ||
| Visual Studio Code | JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use version 1.55 or later. | |
| Teams Toolkit | A Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use 4.0.0 version. | |
| Node.js | Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type. | |
| Microsoft Teams | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, call - all in one place. | |
| Microsoft Edge (recommended) or Google Chrome | A browser with developer tools. | |
| Optional | ||
| Azure Tools for Visual Studio Code and Azure CLI | Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure. | |
| React Developer Tools for Chrome OR React Developer Tools for Microsoft Edge | A browser DevTools extension for the open-source React JavaScript library. | |
| Microsoft Graph Explorer | Microsoft Graph Explorer, a browser-based tool that lets you run a query from Microsoft Graph data. | |
| Developer Portal for Teams | Web-based portal to configure, manage, and distribute your Teams app including to your organization or the Teams store. |
Tip
If you work with Microsoft Graph data, you should learn about and bookmark the Microsoft Graph Explorer. This browser-based tool allows you to query Microsoft Graph outside of an app.
Prepare development environment
After you've installed the required tools, set up the development environment.
Install the Teams Toolkit
The Microsoft Teams Toolkit helps simplify the development process with tools to provision and deploy cloud resources for your app, publish to the Teams store, and more.
You can use the toolkit with Visual Studio Code, or CLI (command-line interface), called TeamsFx.
Open Visual Studio Code and select the Extensions view (Ctrl+Shift+X / ⌘⇧-X or View > Extensions).
In the search box, enter Teams toolkit.
Select Install next to the Teams Toolkit.
The Teams Toolkit icon appears in the Visual Studio Code Activity Bar after it's installed.
You can also find the Teams Toolkit on the Visual Studio Code Marketplace.
Note
The latest version of Teams Toolkit is 4.2.0.
Set up your Teams development tenant
A tenant is like a space, or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where your sideload and test your app. Let's verify if you're ready to develop with the tenant.
Check for sideloading option
After creating the app, you must load your app in Teams without distributing it. This process is known as sideloading. Sign in to your Microsoft 365 account to view this option.
Note
Sideloading is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you will not be able to preview and test your app in Teams locally.
Do you already have a tenant, and do you have the admin access? Let's check if you really do!
Verify if you can sideload apps in Teams:
In the Teams client, select the Store icon.
Select Manage your apps.
Select Publish an app.
Look for the option to Upload a custom app. If you see the option, sideloading apps is enabled.
Note
If you don't have the option to upload a custom app, talk to your Teams administrator.
Create a free Teams developer tenant (optional)
If you don't have a Teams developer account, you can get it free. Join the Microsoft 365 developer program!
Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears.
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.
Get a free Azure account
If you wish to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.
Now you’ve got all tools and set up your account. Next, let's set up your development environment and start building! Select the app you want to do first.
Create project workspace for your tab app
Start Microsoft Teams app development by creating your first app. This app uses the tab capability.
In this page, you learn:
Create your tab project workspace
If the prerequisites are in place, let's begin!
Note
The Visual Studio Code UI shown is from Mac. It may differ depending on your operating system, Teams Toolkit version, and environment.
Open Visual Studio Code.
Select the Teams Toolkit
icon in the Visual Studio Code Activity Bar.Select Create a new app.
Select Create a new Teams app to create an app using Teams Toolkit.
Ensure that Tab is selected as the capability that you want to build in your app. Select OK.
Select JavaScript as the programming language.
Select Default folder to store your project root folder in default location.
You can also change the default location by the following steps:
Select Browse.
Select the location for project workspace.
Select the Select Folder.
Enter a suitable name for your app. Select Enter.
The Teams tab app is created in a few seconds.
After your app is created, Teams Toolkit displays the following message:
You can select Local debug to preview your project.
A quick recap of creating a Teams app.
Watch this short recap for creating a Teams app.
Take a tour of the tab app source code
Teams Toolkit provides all components for building an app. After creating the project, you can view the project folders and files in the Explorer area of Visual Studio Code.
Although you're free to choose any UI framework (or not to use any), this sample template code provides a scaffolding with React components.
Among other items in this directory structure, the Toolkit maintains:
| Folder name | Contents |
|---|---|
.fx/configs |
Configuration files that user can customize for the Teams app. |
- .fx/configs/config.<envName>.json |
Configuration file for every environment. |
- .fx/configs/azure.parameters.<envName>.json |
Parameters file for Azure BICEP provision for every environment. |
- .fx/configs/projectSettings.json |
Global project settings that apply to all environments. |
- .fx/states |
Provision output that is generated by Teams Toolkit. The toolkit creates this folder after you provision resources for your app. |
- .fx/states/state.<envName>.json |
Provision output file for every environment. |
- .fx/states/<env>.userdata |
Sensitive user data for the provision output for every environment. |
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 |
When you add the cloud functionality, Teams Toolkit adds the necessary folders to the project. The api folder holds the code to any Azure Functions you write.
Build and run your first tab app
After you set up your project workspace with Teams Toolkit, build your tab project. You need to sign in to your Microsoft 365 account.
Sign in to your Microsoft 365 account
Use your Microsoft 365 account to sign in to Teams. If you're using a Microsoft 365 developer program tenant, the admin account you set up while registering is your Microsoft 365 account.
Open Visual Studio Code.
Select the Teams Toolkit
icon in the sidebar.Select Sign in to M365.
Your default web browser opens to let you sign in to the account.
Sign in to your Microsoft 365 account using your credentials.
Close the browser when prompted and return to Visual Studio Code.
Return to Teams Toolkit within Visual Studio Code.
The ACCOUNTS section of the sidebar shows your Microsoft 365 account name. Teams Toolkit displays Sideloading enabled if sideloading is enabled for your Microsoft 365 account.
Now you're ready to build the app and run it in the local environment!
Build and run your app locally in Visual Studio Code
To build and run your app locally:
From Visual Studio Code, select F5 to run the application in debug mode.
Learn what happens when you run your app locally in the debugger.
In case you're wondering, when you press the F5 key, Teams Toolkit:
- Checks for the following prerequisites:
- You're logged in with a Microsoft 365 account.
- Sideloading is enabled for your Microsoft 365 account.
- Supported Node.js version is installed.
- Development certificate for localhost is installed.
- Port is available for the tab app.
Note
If Teams Toolkit is unable to check a particular prerequisite, it prompts you to check it.
- Install NPM packages.
- Registers the app with Azure AD and configures the app.
- Registers the app in Teams Developer Portal and configures the app.
- Starts the tab app.
- Starts Teams in a web browser and sideloads the tab app.
Note
When you run the app for the first time, all dependencies are downloaded, and the app is built. A browser window opens when the build is complete. This process can take 3-5 minutes to complete.
The toolkit prompts you to install a local certificate, if necessary. This certificate allows Teams to load your application from
https://localhost.Select Yes if the following dialog appears:
Or select Continue, depending on your operating system:
Teams web client opens in a browser window.
Note
If the toolkit doesn't prompt you to install a certificate, you must install the certificate manually. For more information, see Add manual certificate.
Sign in with your Microsoft 365 account, if prompted.
Select Add when prompted to sideload the app onto Teams on your local machine.
Congratulations, your first app is running on Teams!
You can add SSO feature to retrieve the user details. You can do normal debugging activities, such as setting breakpoints, as if it were any other web application. The app supports hot reloading. If you change any file within the project, the page will be reloaded.
Learn how to troubleshoot if your app doesn't run locally.
To successfully run your app in Teams, ensure that you've enabled sideloading in your Teams account. You can learn more about sideloading in the Prerequisites section.
Deploy your first Teams app
You've learned to create, build, and run Teams app with Tab app. The final step is to deploy your app on Azure.
Let's deploy the first app with Tab capability on Azure using Teams Toolkit.
Sign in to your Azure account
Use this account to access the Microsoft Azure portal and to provision new cloud resources to support your app.
Open Visual Studio Code.
Open the project folder in which you created the tab app.
Select the Teams Toolkit
icon in the sidebar.Select Sign in to Azure.
Tip
If you have the Azure Account extension installed and are using the same account, you can skip this step. Use the same account as you're using in other extensions.
Your default web browser opens to let you sign in to the account.
Sign in to your Azure account using your credentials.
Close the browser when prompted and return to Visual Studio Code.
The ACCOUNTS section of the sidebar shows the two accounts separately. It also lists the number of usable Azure subscriptions available to you. Ensure you have at least one usable Azure subscription available. If not, sign out and use a different account.
Now you're ready to deploy your app to Azure!
Congratulations, you've created a Teams app! Now let's go ahead and learn how to deploy one of the apps to Azure using the Teams Toolkit.
Deploy your app to Azure
Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning). Then, your app's code is copied into the created cloud resources. For this tutorial, you'll deploy the tab app.
What's the difference between Provision and Deploy?
The Provision step creates resources in Azure and Microsoft 365 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's common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it's separate from the deployment step.
Select the Teams Toolkit
icon in the Visual Studio Code sidebar.
Select Provision in the Cloud.
Select anyone of the existing subscription.
Select a resource group to use for the Azure resources.
A dialog warns you that costs may be incurred when running resources in Azure.
Select Provision.
The provisioning process creates resources in the Azure cloud. It may take 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:
If you want, you can view the provisioned resources. For this tutorial, you don't need to view resources.
The provisioned resource appears in the Environment section.
Select Deploy to the Cloud from the Deployment panel after provisioning is complete.
As with provisioning, deployment 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.
Now, you can use the same process to deploy your Bot and Message Extension apps to Azure.
Note
Your app is hosted using Azure resources.
Run the deployed app
Once the provisioning and deployment steps are complete:
Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.
Select Launch Remote (Edge) from the launch configuration drop-down.
Select the Start debugging (F5) to launch your app from Azure.
Select Add when prompted to sideload the app onto Teams.
Congratulations, your first tab app is running in your Azure environment!
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 is a two-step process. You provision the resources on an active Azure subscription, and then deploy or upload the backend and frontend code for the application to Azure.
- The backend, if configured, uses various 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.
Congratulations!
You've done it!
You've created a tab app.
Now that you've learned to create a basic app, you can move on to creating more complex apps. To start with, try adding capabilities to your existing apps.
To add capabilities to your existing app:
Select Add features from the Development section of the Teams Toolkit sidebar.
Select the capability you want to add to your app.
That's it! Teams Toolkit adds the scaffolding for the new capability to your app's directory structure. Follow the procedures to build and deploy the app, and your app will have multiple capabilities.
You've completed the tutorial to build tab app with JavaScript.
Have an issue with this section? If so, please give us some feedback so we can improve this section.
Feedback
Submit and view feedback for