Create a custom personal tab using Node.js and the Yeoman Generator for Microsoft Teams

Note

This quickstart follows the steps outlined in the Build Your First Microsoft Teams App Wiki found in the Microsoft OfficeDev GitHub repository.

In this quickstart we'll walk-through creating a custom personal tab using the Teams Yeoman generator. We'll also upload the application to Team.

Prerequisites

  • To complete this quickstart you will need an Office 365 tenant and a team configured with Allow uploading custom apps enabled. To learn more, see Prepare your Office 365 tenant.

    • If you don't currently have an Office 365 account, you can sign up for a free subscription through the Office 365 Developer Program. The subscription will remain active as long as you're using it for ongoing development. See Welcome to the Office 365 Developer Program.

In addition, this project requires that you have the following installed in your development environment:

  • Any text editor or IDE. You can install and use Visual Studio Code for free.

  • Node.js/npm. You should use the latest LTS version. The Node Package Manager (npm) will install into your system with the installation of Node.js.

  • After you've successfully installed Node.js, install the Yeoman and gulp-cli packages by typing the following in your command prompt:

    npm install yo gulp-cli --global
    
  • Install the Microsoft Teams Apps generator by typing the following in your command prompt:

    npm install generator-teams --global
    

Generate your project

  • Open a command prompt and create a new directory for your tab project.

  • To start the generator, navigate to your new directory and type the following command:

    yo teams
    
  • Next, you'll provide a series of values that will be used in your application's manifest.json file:

    generator opening screenshot

    What is your solution name?

    This is your project name. You can accept the suggested name by pressing enter.

    Where do you want to place the files?

    You're currently in your project directory. Press enter.

    Title of your Microsoft Teams app project?

    This is your app package name and will be used in the app manifest and description.

    Your (company) name? (max 32 characters)

    Your company name will be used in the app manifest.

    Which manifest version would you like to use?

    Select the default schema.

    Quick scaffolding? (Y/n)

    The default is yes; enter n to enter your Microsoft Partner Id.

    Enter your Microsoft Partner Id, if you have one? (Leave blank to skip)

    This field isn't required and should only be used if you're already part of the Microsoft Partner Network.

    What do you want to add to your project?

    Select ( * ) A Tab.

    The URL where you will host this solution?

    By default the generator suggests an Azure Web Sites URL. You'll only be testing your app locally, therefore, a valid URL is not necessary to complete this quickstart.

    Would you like to include Test framework and initial tests? (y/N)

    Choose not to include a test framework for this project. The default is yes; enter n.

    Would you like to use Azure Applications Insights for telemetry? (y/N)

    Choose not to include Azure Application Insights. The default is no; enter n.

    Default Tab Name (max 16 characters)?

    Name your tab. This tab name will be used throughout your project as a file/URL path component.

Create a configurable or static tab

Use the arrow keys to select static tab.

Important

The path component yourDefaultTabNameTab, referenced in this quickstart, is the value that you entered in the generator for Default Tab Name plus the word Tab.

For example: DefaultTabName: MyTab => /MyTabTab/

Create your personal tab

To add a personal tab to this application you'll create a content page and update existing files:

  • In your code editor, create a new HTML file, personal.html and add the following markup:

    <!DOCTYPE html>
    <html>
        <head>
            <meta charset="UTF-8">
            <title>
                <!-- Todo: add your a title here -->
            </title>
            <meta name="viewport" content="width=device-width, initial-scale=1.0">
            <!-- inject:css -->
            <!-- endinject -->
        </head>
            <body>
                <h1>Personal Tab</h1>
                <p><img src="/assets/icon.png"></p>
                <p>This is your personal tab!</p>
            </body>
    </html>
    
  • Save personal.html in your application's web folder:

    ./src/app/web/<yourDefaultTabNameTab>/personal.html
    
  • Open manifest.json in your code editor:

    ./src/manifest/manifest.json/
    

Add the following to the empty staticTabs array (staticTabs":[]) and add the following JSON object:

{
    "entityId": "personalTab",
    "name": "Personal Tab ",
    "contentUrl": "https://{{HOSTNAME}}/<yourDefaultTabNameTab>/personal.html",
    "websiteUrl": "https://{{HOSTNAME}}",
    "scopes": ["personal"]
}

Remember to update the "contentURL" path component yourDefaultTabNameTab with your actual tab name.

  • Save the updated manifest.json.

  • Your content page must be served in an IFrame. Open Tab.ts in your code editor:

    ./src/app/<yourDefaultTabNameTab>/<yourDefaultTabNameTab>.ts
    
  • Add the following to the list of IFrame decorators:

     @PreventIframe("/<yourDefaultAppName>TabNameTab>/personal.html")
    
  • Make sure to save the updated Tab.ts file. Your tab code is complete.

Build and Run Your Application

Open a command prompt in your project directory to complete the next tasks.

Create the app package

You'll need an app package to test your tab in Teams. It's a zip folder that contains the following required files:

  • A full color icon measuring 192 x 192 pixels.
  • A transparent outline icon measuring 32 x 32 pixels.
  • A manifest.json file that specifies the attributes of your app.

The package is created via a gulp task that validates the manifest.json file and generates the zip folder in the ./package directory. In the command prompt enter:

gulp manifest

Build your application

The build command transpiles your solution into the ./dist folder. Next,enter:

gulp build

Run your application in localhost

Start a local web server by entering the following:

gulp serve

Enter http://localhost:3007/<yourDefaultAppNameTab>/ in your browser and view your application's home page:

home page screenshot

To view your personal tab, go to http://localhost:3007/<yourDefaultAppNameTab>/personal.html

personal tab screenshot

Establish a secure tunnel to your tab

Microsoft Teams is an entirely cloud-based product and requires that your tab content be available from the cloud using HTTPS endpoints. Teams doesn't allow local hosting, therefore, you need to either publish your tab to a public URL or use a proxy that will expose your local port to an internet-facing URL.

To test your tab extension, you'll use ngrok, which is built into this application. Ngrok is a reverse proxy software tool that will create a tunnel to your locally running web server's publicly-available HTTPS endpoints. Your server's web endpoints will be available during the current session on your local machine. When the machine is shut down or goes to sleep the service will no longer be available.

In your command prompt, exit localhost and enter the following:

gulp ngrok-serve

Important

After your tab has been uploaded to Microsoft teams, via ngrok, and successfully saved, you can view it in Teams until your tunnel session ends.

Upload your application to Teams

  • Open the Microsoft Teams client. If you use the web based version you can inspect your front-end code using your browser's developer tools.
  • In the YourTeams panel on the left, select the ... menu next to the team that you're using to test your tab and choose Manage team.
  • In the main panel select Apps from the tab bar and choose Upload a custom app located in the lower right-hand corner of the page.
  • Open your project directory, browse to the ./package folder, select the zip folder, right-click, and choose Open. Your tab will upload into Teams.

View your personal tabs

In the navbar located at the far-left of the Teams client, select the ... menu and choose your app from the list.

Next step