Microsoft Teams is a Microsoft collaboration tool and gained more popularity during COVID-19, becoming Microsoft's fastest-growing business app ever. But beyond the capabilities of collaboration and meetings, it comes with a rich library of extension apps which you can add to your teams.
Microsoft Teams lets apps integrate into your team channels and enables team members to switch between your application and conversations smoothly with the same context using Single-Sign-On (SSO).
In this article, I'm going to walk you through the steps to create your first app for Microsoft Teams and add it as a tab to your organization team channel.
Before we start, you need to have a Microsoft Teams account. It could be your personal or organization account. For this tutorial, I recommend using your personal account so you can add a custom app to the channels. If you want to use your organization account you need to be the owner of the team or have access to enable "Custom Teams App". You can find the instructions on how to enable custom app in Microsoft website.
Prepare your environment
We bootstrap this project using an open-source library called generator-teams from Microsoft 365 Patterns and Practices (PnP). This generator creates a JavaScript project using React framework. The generator itself uses a tool called Yeoman which is a client-side opinionated template generator. It takes care of creating everything to get started without any manual setup.
First, you need to have NodeJS installed on your machine. You can install the latest LTS version from NodeJS website.
To be able to scaffold the project you need Yeoman tool and for running build tasks you need Gulp CLI which you can install using the following command:
npm i -g yo gulp-cli
Install generator-teams globally so yo command can use this template and scaffold the project.
npm i -g generator-teams
Create the App
Now that the dependencies are installed you can use the yo command to generate the template code. The following command generates the template based on your answers. For the sake of this tutorial we'll keep it simple and we won't include any extra features in this project.
yo teams
For manifest version select v1.5 which is the current general available schema and for hosting URL go with the default value for now and we'll change it in the config file later.
It'll take a few minutes to complete generating the code template.
Project structure
The project has been scaffolded to a React project. Open the project in your favourite editor and navigate to src directory. This is the directory that holds all the source code for your application.
Your app component is in src/app/scripts/{your-app-name}/{your-app-name}.tsx. This component is the entry point to your app and you can see that it's a React component with the name of your application. If you want to customize your application you need to change this component.
For building and bundling of the application, a combination of Gulp and Webpack has been used. In /gulpfile.js you can see all the commands you can run against your code. Typically you don't need to modify this file since it's been designed in a way to work out of the box. But, in this tutorial, we will modify this file to make the build process more efficient.
For a more detailed description of each part of your app read the README.md file in your project.
Run your application
For running your application locally you need a local webserver. gulp serve command builds the project and starts a local web server on port 3007. If you navigate to http://localhost:3007/{your-application-name} you should be able to see your application running.
Congrats! Now you have a running app in your browser which you can upload to Microsoft Teams. But before that, we are going to fix the build performance in the next step.
Improve build performance
If you navigate to gulpfile.js and take a look at the available commands you'll see that the serve task is comprised of other tasks like build and watch, likewise the build task uses webpack and styles tasks. If you trace all the sub-commands of the serve, you will see that it builds the project using Webpack, watches for file changes (in debug mode), and rebuilds the project on any code change.
If you run the application in debug mode using npm run debug and modify any file in the src folder it'll trigger a new build for the entire project including the node_modules folder which is an expensive operation for every single change. On my machine, it took around 11 seconds for the "Hello World" project and it'll increase as you add more dependencies to your application.
For fixing this issue we are going to use Webpack SplitChunk Plugin which splits the bundles of vendor script (node modules) and application script.
The first step to achieve this is to add vendor script to the inject sources of gulp.config.js file. This will tell gulp to include in the final HTML any JavaScript file where the name starts with vendors. All the node_modules and third-party libraries will go into this file and build won't touch this file on application code change. This has a huge impact on build time especially if you have many dependencies.
Next, swap Gulp watch with Webpack watch by removing watch from gulpfile.js...
...and adding Webpack watch as a script to package.json.
Finally, you need to enable the split chunk plugin by adding it to webpack.config.js:
Now, if you run your local server using gulp serve, it'll only build the project for the first time and start the webserver. For watch you need to run npm run watch. If we test the application using this new watch we can see that the build time has been reduced to around 500 milliseconds which is around 20 times faster for the almost empty project.
You can confirm split chunk is working by navigating to /dist/web/scripts where you can see two script files, one for node modules (vendors~client.js) and the other for your application code (client.js). It's obvious why the default approach should take longer by looking at the size of the vendor script bundle which is around 6 MB compared to the size of the client script which is 28 KB. Another point is the modified date of the vendor script bundle, which shows that this file hasn't been modified after the first build but client.js has been recreated every time we modified the source code.
Upload to the Teams
Uploading your application to Microsoft teams is done using a manifest file. If you run gulp manifest, it’ll generate a zipped manifest file in the /package directory. You can change the manifest details by modifying /src/manifest/manifest.json.
It's important to know that Microsoft Teams doesn't provide you with the hosting space for your app and you need to host it yourself somewhere which is publicly accessible. If you’re just going to test your application you can use ngrok to host it from your localhost. Run the following command to host it locally:
gulp ngrok-serve
If you are using the free version of ngrok, when creating a proxy, it'll create a random subdomain for you. You'll then need to update the .env file with the automatically generated host and run gulp manifest to create the manifest file. You can confirm that your application is accessible from the internet by navigating to the ngrok URL.
Once you've created the manifest package and tested that your application is accessible from the ngrok domain, open your Teams client, click on "Apps" at the bottom-left corner and select "Upload a custom app". Select your manifest package zip file located in /package/{your-app-name}.zip and add it to your application gallery.
Finally, you need to add your application as a tab to any channel you want. Click on the plus button next to your channels tab and add your application.
Congratulations! You've built and deployed your first Microsoft Teams App.