Hello World with SPFx - Teams

SharePoint Framework (SPFx) is a development model to build client-side solutions for Microsoft Teams and SharePoint. Your SPFx Teams app is hosted on Microsoft 365. It provides full support for developing and hosting your client-side SPFx solution. You can integrate your SharePoint Framework solution with:

SharePoint data and extend Microsoft Teams.
Your business APIs secured with Microsoft Entra ID.

For this tutorial, start Microsoft Teams app development with SPFx by building your first app with a tab capability.

Diagram showing this app has three features. Tab is highlighted.

Note

Teams Toolkit offers only the tab capability in a Teams app built with SharePoint Framework. The bot and message extension capabilities aren't available.

Prerequisites

4 minutes remaining

Here's a list of tools you need for building and deploying your apps.

	Install	For using...
Required
	Visual Studio Code	JavaScript or TypeScript, build environments. Use latest version.
	Teams Toolkit	A Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use Teams Toolkit v5.
	Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
	Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.
Optional
	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 publish your Teams app including to your organization or the Microsoft 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 install the required tools, set up the development environment.

Install Teams Toolkit

Microsoft Teams Toolkit helps simplify the development process with tools to provision and deploy cloud resources for your app and publish to the Teams Store.

You can use Teams Toolkit with Visual Studio Code or a command-line interface called TeamsFx CLI.

Visual Studio Code
Command Line

Open Visual Studio Code and select Extensions (Ctrl+Shift+X or View > Extensions).
In the search box, enter Teams Toolkit.
Select Install.

The Teams Toolkit icon appears in the Visual Studio Code Activity Bar.

You can also install Teams Toolkit from the Visual Studio Code Marketplace.

To install the TeamsFx CLI, use the npm package manager and enter the following command in Command prompt:

Bash

npm install -g @microsoft/teamsfx-cli

Depending on your configuration, you might need to use sudo to install the CLI:

Bash

sudo npm install -g --unsafe-perm @microsoft/teamsfx-cli

This condition is more common on Linux and macOS systems.

Ensure you add the npm global cache to your PATH. This step is normally done as part of the Node.js installer.

You can use the CLI with the teamsfx command. Verify that the command is working by running teamsfx -h.

Caution

Before you can run TeamsFx in PowerShell terminals, you must enable the remote signed execution policy for PowerShell.

Set up your Teams development tenant

A tenant is a space or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where you upload and test your app. Let's verify if you're ready to develop with the tenant.

Check for upload an app option

After creating your custom app, you must upload your app to Teams with the Upload a custom app option. Sign in to your Microsoft 365 account to check if this option is enabled.

The following steps help you verify if you can upload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

Note

If you don't find the option to upload a custom app, contact your Teams administrator.

Create a free Teams developer tenant (optional)

If you don't have a Teams developer account, 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.

I ran into an issue

SharePoint Collection Site Administrator account

Ensure that you have an Administrator account for a SharePoint Site Collection. You need this account at deployment for hosting. If you're using a Microsoft 365 developer program tenant, you can use the administrator account you created at the time.

Now you’ve got all tools and set up your account. Next, let's set up your development environment and start building!

Create project workspace for your tab app

3 minutes remaining

This tutorial walks you through the steps to create, build, and deploy a Teams app using SharePoint Framework SPFx. This app will have a tab capability.

In this tutorial, you learn:

How to set up a new project with Teams Toolkit
About the directory structure of your app

Important

Before you start creating the project workspace, ensure that you're not signed into any Microsoft 365 or Azure account.

Create your project

If the prerequisites are in place, let's begin!

Visual Studio Code
Command line

Open Visual Studio code.
Select the Teams Toolkit icon in the Visual Studio Code Activity Bar.
Select Create a new app.
Select Tab.
Select SPFx.
Select Create a New SPFx Solution.
Select an option for scaffolding.
Select React in the Framework section.
Select Enter to accept the default Web Part Name.
Select your Workspace folder by choosing your required folder.
Enter a suitable Application name for your app. Press Enter.

After your app is created, the Teams Toolkit displays the following message:

Select Local debug to preview your project.

Teams Toolkit invokes Yeoman CLI to scaffold your Teams app, and install the required dependencies in the process.

The scaffolding takes a couple of minutes.

A quick recap of creating a Teams app.

Create a Teams app

I ran into an issue

Use the teamsfx CLI to create your first project. Start from the folder where you want to create the project folder.

Bash

teamsfx new

The CLI walks through some questions to create the project. Every question includes an instruction on answering it, for example, Use arrow keys to select an option. When you've answered the question, select Enter to confirm it.

Select Create a new Teams app.
Select Tab.
Select SharePoint Framework (SPFx) frontend hosting.
Select React Framework.
Press Enter for the Web Part Name.
Enter a suitable name for your app, like helloworld. The name of the app must be alphanumeric.

Your project is created after all the questions are answered.

I ran into an issue

Take a tour of the source code

After project creation, you have the components to build a basic personal app. You can view the project directories and files in the Explorer area of Visual Studio Code.

Screenshot showing app project files for a personal app in Visual Studio Code.

The Toolkit creates scaffolding for you in the project directory for the tab capability.

Among other items in this directory, the Teams Toolkit contains:

appPackage: contains the app icons, color.png and outline.png.
manifest.local.json: contains the app manifest for local debug.
manifest.json: contains the app manifest for publishing to Developer Portal for Teams.
.vscode/Settings.json: the settings you chose when creating the project.

As you selected an SPFx Web part project, the following files are relevant to your UI:

SPFx/src/webparts/{webpart}: contains your SPFx web part.
.vscode/launch.json: describes the debugging configurations available in the debug palette.

Build your tab app

2 minutes remaining

After you set up your project workspace with Teams Toolkit, build your tab project. You need to sign in to your Microsoft 365 account.

In this page, you learn to build and run your first app.

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.

Visual Studio Code
Command line

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.

Now you're ready to build the app and run it locally!

I ran into an issue

Sign in to Microsoft 365 with the TeamsFx CLI.

Bash

    teamsfx account login m365

Your default web browser opens to let you sign in to the account. Sign in to your account using your credentials. Close the browser when you're prompted.

The account logins are shared between Visual Studio Code and the TeamsFx CLI.

Now that the development environment is configured, you can create, build, and deploy your first Teams app.

I ran into an issue

Build and run your app locally in Visual Studio Code

To build and run your app locally:

Select the Run and Debug icon from the Visual Studio Code sidebar.
Select one of the following options to run and debug the app.
- Teams workbench (Edge)
- Teams workbench (Chrome)
Select the play button or select the F5 key to start debugging.

Note

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 process can take a few minutes to complete.

The Toolkit may 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:

Teams web client opens in a browser window.
Select Add.
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel or chat from the list, and move through the dialog to select Go.
Select the web app version, if you're asked to switch to Teams desktop. You can see the HTML, CSS, and JavaScript code in a standard web development environment.
Select Load debug scripts, if you're prompted to load debug scripts before your custom app is uploaded in Teams.

Congratulations, your first app is running on Teams!

Your app should now be running. You can debug the app as any other SPFx web part (such as setting breakpoints).

Tip

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

Learn what happens when you use Local Workbench for debugging your app.

Local workbench is the default option to run and debug an app in Visual Studio Code. For this tutorial, it's recommended that you choose to debug your app with the Teams workbench, however, you can choose the Local workbench to explore web part layouts.

Note

This interface is intended only for exploring how a web part may appear in a mobile or a tablet. You would need to write the code for including them in your app, and then deploy it to view them.

To explore web part layouts using local workbench:

Select Local workbench, and then select F5 to run and debug the app.

The SharePoint Web Part Workbench opens in the browser to let you add, edit, and remove web parts.
Select Add Web Part in column one + icon to add your web part.
Select your web part from the menu.
Select Add a new section + icon to choose column layout for your web parts.
Use this interface to try out different layouts for web parts:
- View Web Part Data for your layout.
- Try changing between different layouts, text, color, and more.
- Use the Preview button to view the web parts.
- View the web part layout in different Mobile or Tablet devices.
- Save or discard any changes in the layout to continue trying possible layouts.
Close the browser window to stop local workbench debugging when you're ready.

I ran into an issue

Deploy your first Teams app

100% complete!

You've learned to create, build, and run Teams app with Tab capability. The final step is to deploy your app.

Let's deploy the first app with Tab capability on SharePoint using Teams Toolkit.

In this page, you learn to:

Deploy your first app
Distribute the app package on SharePoint

Deploy your app to SharePoint

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

Visual Studio Code
Command line

Open Visual Studio Code.
Select the Teams Toolkit from the sidebar by selecting the Teams icon.
Select Provision under LIFECYCLE.

The Toolkit updates the progress in the bottom-right corner. After a few seconds, you can see the following notice:
After provisioning is complete, select Deploy under LIFECYCLE.

The app package is built, and uploaded to the SharePoint site. The Teams Toolkit displays a message with the local path where the app package is saved.

After the package is built, Teams Toolkit displays a message with the url of the SharePoint site where your app package has been uploaded.

You can either publish to Teams or select the SharePoint site.
- Publish to Teams (#publish-to-teams)
- Select the link of the SharePoint site (#select-the-link-of-the-sharepoint-site)

Publish to Teams

Select Publish to Teams.
Select Admin portal.
Select Manage Apps and search your app in the search section to select your app.
Select Publish to publish your app in Teams.
Open the Teams application (or sign in at https://teams.microsoft.com).
Select the triple-dot on the sidebar, then select All apps.

The app displays in the Apps built for your org category. You can add the app from there.
Select your app, and then select Add.
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel or chat from the list, and move through the dialog to select Go.

Congratulations! Your app is now added to Teams.

Select the link of the SharePoint site

Select the link of the SharePoint site.

The SharePoint site opens to the Apps home page. Follow the procedure to distribute the app on SharePoint.

I ran into an issue

In your terminal window:

Run teamsfx provision.

Bash

teamsfx provision

Run teamsfx deploy.

Bash

teamsfx deploy

When prompted, select Build SharePoint Package.

Follow the procedure to distribute the app on SharePoint.

I ran into an issue

Distribute the app package on SharePoint

You can find the app package uploaded at the SharePoint site. To distribute the app and sync it to Teams:

Select Distribute apps for SharePoint.

The Apps for SharePoint home page opens. Your app is listed in this page.
Select the FILES tab.
Select the package you deployed, then select Sync to Teams.

Note

The Sync to Teams process can take a few minutes. You will see a message in the browser indicating that the app has been successfully synchronized to Teams.
Open the Teams application (or sign in at https://teams.microsoft.com).
Select 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.
Select your app, and then select Add.
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel or chat from the list, and move through the dialog to select Go.

Congratulations! Your app is now added to Teams.

I ran into an issue

Share via

Build your first app with SPFx

Prerequisites

Prepare development environment

Install Teams Toolkit

Set up your Teams development tenant

Check for upload an app option

Create a free Teams developer tenant (optional)

SharePoint Collection Site Administrator account

Create project workspace for your tab app

Create your project

Take a tour of the source code

Build your tab app

Build and run your app locally in Visual Studio Code

Deploy your first Teams app

Deploy your app to SharePoint

Publish to Teams

Select the link of the SharePoint site

Distribute the app package on SharePoint