DOCSEARCHbyAlgolia
Submit Docs

Microsoft Teams JavaScript Client Library

repository·main·Indexed 19 days ago

https://github.com/officedev/microsoft-teams-library-js

The Microsoft Teams JavaScript client library provides the essential SDK for developers to build applications and services that integrate with Microsoft Teams, Outlook, and Office. The repository includes the teams-js package and various test applications for Blazor, SSR (React/NextJS), performance measurement, and general SDK testing.

Tokens
15.6K
Snippets
53
Records
75
Agent score
67%

What's inside microsoft-teams-library-js

  1. Overview of Microsoft Teams JavaScript client library

    main
    The Microsoft Teams JavaScript client library is used to integrate custom services and applications with Microsoft Teams, Outlook, and Office. The core functionality is provided by the @microsoft/teams-js package. This repository is a monorepo containing the core library, testing applications (Performance, Functional, and SSR), and analysis tools.

  3. Use the Bundle analysis app to monitor @microsoft/teams-js size

    main
    The Bundle analysis app is a specialized utility used to monitor the bundle size of the @microsoft/teams-js package. It contains minimal code that imports the library and is configured with Webpack to generate zipped Webpack stats. These stats allow developers to compare bundle sizes and dependency trees across different commits or changes to track growth or regressions.

  4. Implement `ApiWithTextInput` for complex API inputs

    main

    When using the ApiWithTextInput component, there are two implementation patterns depending on the API requirements:

    1. Simple APIs (No validation required): Provide a simple onClick callback. The component will attempt to parse the input as JSON and pass it to the callback.
    2. Complex APIs (Validation required): Provide both validateInput and submit callbacks:
      • validateInput: Receives the parsed JSON input. It must throw an exception if input requirements are not met (e.g., a required property is missing). If validation fails, the error is displayed in the Test App UI.
      • submit: Called only if validateInput passes.

  5. Handle Promise polyfills for older browsers

    main

    The Teams client library depends on the Promise type. If you are targeting older browsers or devices that do not support Promises natively (such as IE 11), you must provide a global polyfill like es6-promise in your application.

    Important: If using a <script> tag, ensure the polyfill is included and initialized before the Teams client library is initialized.

  7. How the Runtime object and versioning work

    main

    The Runtime interface (defined in packages/teams-js/src/public/runtime.ts) describes the capabilities and configuration of the Microsoft Teams host. The Runtime object is versioned so that the teams-js library can correctly parse and support older versions of the host environment.

    Versioning follows these rules:

    • Major Version Change: Required when it is impossible to upgrade or downgrade between versions without losing functionality. This occurs if capabilities are merged, split, or removed, or if a required property is added that might not be present in older hosts.
    • Minor Version Change: Required when the previous version can be transformed into the next version (and vice versa) without any loss of teams-js functionality. This includes renaming or moving supported capabilities, or adding optional properties.

  8. Locally generate TeamsJS v2 reference documentation

    main

    You can generate the reference documentation for TeamsJS v2 locally by running the docs script. This can be executed from either the monorepo root or the packages/teams-js directory. The output will be located in packages/teams-js/docs.

    pnpm run docs

  9. Build and test the entire monorepo

    main

    To build the complete project, including the teams-js package and all included test applications, follow these steps from the repository root:

    1. Clone the repository: git clone https://github.com/OfficeDev/microsoft-teams-library-js.git
    2. Install dependencies: pnpm install (Note: pnpm@9.0.6 or greater is required).
    3. Build the project: pnpm build
    4. Run unit tests: pnpm test
    git clone https://github.com/OfficeDev/microsoft-teams-library-js.git
npm install -g pnpm@9.0.6
pnpm install
pnpm build
pnpm test

  11. Run the SSR Test App with HTTPS

    main

    To run the SSR Test App in the Orange app, HTTPS is required. You can use either local SSL certificates or ngrok.

    Option 1: Using Local SSL Certificates (Recommended)

    1. Generate certificates: The easiest way is to use the automated script from the monorepo root:

      pnpm setup-ssr-app-cert

      This script checks for mkcert, installs the local CA, and generates certificates in apps/ssr-test-app/certs/.

      Manual Setup (if the automated script is not used):

      • Install mkcert (e.g., brew install mkcert on macOS).
      • Run mkcert -install to install the local CA.
      • Navigate to apps/ssr-test-app/certificates and run mkcert localhost to create localhost.pem and localhost-key.pem.

    2. Run the app: From the monorepo root:

      pnpm start-ssr-app:https
       Or from the `ssr-test-app` directory:
   ```bash
pnpm dev:https   # For development
pnpm start:https # For production (requires pnpm build first)

    The app will be available at https://localhost:3000.

    Option 2: Using ngrok

    If you prefer not to manage certificates, you can use ngrok to create a secure HTTPS tunnel:

    1. Start the app normally in one terminal:
      pnpm dev
    2. Start ngrok in another terminal:
   ```bash
ngrok http 3000
    pnpm setup-ssr-app-cert
pnpm start-ssr-app:https

  12. Run the Blazor Test App locally

    main

    The Blazor Test App is a C#/Blazor application used to verify that changes to the teams-js package do not break functionality for C# Teams apps.

    To run the app from the monorepo root, you must first ensure the Teams JavaScript client SDK is installed and built, as the app requires the latest compiled MicrosoftTeams.min.js to be present in blazor-test-app/wwwroot/js.

    Prerequisites:

    • The teams-js package must be built so that MicrosoftTeams.min.js is generated.
    • The MicrosoftTeams.min.js file must be located in blazor-test-app/wwwroot/js (this happens automatically when building from the monorepo root).

    Steps to run from monorepo root:

    1. Install dependencies and build the SDK.
    2. Start the Blazor app.

    Steps to run directly from the project directory: If you have already built the Teams JavaScript client SDK, you can run it directly from the blazor-test-app directory.

    # From the monorepo root
cd {monorepo root}
pnpm install
pnpm build
pnpm start-blazor-app

# OR from the blazor-test-app directory (if SDK is already built)
cd apps/blazor-test-app
pnpm build
pnpm start