### Install and Build Teams SDK, then Start SSR App
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Steps to install dependencies, build the Teams JavaScript client SDK, and then start the SSR Test App from the monorepo root.
```bash
cd {monorepo root}
// Ensuring you have installed and built the Teams JavaScript client SDK
pnpm install
pnpm build
pnpm start-ssr-app
```
--------------------------------
### Install and Build SDK, then Build and Start Perf App
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-perf-test-app/README.md
Commands to install dependencies, build the Teams JavaScript client SDK, build the perf test app, and start it. Assumes you are in the monorepo root directory.
```bash
cd {monorepo root}
// Ensuring you have installed and built the Teams JavaScript client SDK
pnpm install
pnpm build-sdk
pnpm build-perf-app
pnpm start-perf-app
```
--------------------------------
### Install and Build Teams SDK
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/README.md
Commands to install dependencies, build the Teams JavaScript client SDK, and start the test app from the monorepo root.
```bash
cd {monorepo root}
// Ensuring you have installed and built the Teams JavaScript client SDK
pnpm install
pnpm build
pnpm start-test-app
```
--------------------------------
### Install and Build Teams JavaScript Client SDK
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/README.md
Commands to install dependencies, build the Teams JavaScript client SDK, and start the Blazor test app.
```bash
cd {monorepo root}
// Ensuring you have installed and built the Teams JavaScript client SDK
pnpm install
pnpm build
pnpm start-blazor-app
```
--------------------------------
### Build and Start Perf App from Project Directory
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-perf-test-app/README.md
Alternative commands to build and start the perf test app directly from its project directory, assuming the Teams JavaScript client SDK is already built.
```bash
pnpm build
pnpm start
```
--------------------------------
### Example Beta Release CDN URL
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases
Example of the CDN URL for a specific beta release (version 2.19.0-beta.1).
```html
https://res-sdf.cdn.office.net/teams-js/2.19.0-beta.1/js/MicrosoftTeams.min.js
```
--------------------------------
### Install Dependencies
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
Install project dependencies using pnpm. Ensure you have pnpm version 9.0.6 or greater installed globally.
```bash
pnpm install
```
--------------------------------
### Run SSR App Normally and Start ngrok
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Instructions for running the SSR Test App using ngrok for an HTTPS connection. This involves starting the app in one terminal and ngrok in another.
```bash
# In one terminal, start the app normally
pnpm dev
# In another terminal, start ngrok
ngrok http 3000
```
--------------------------------
### Handle Authentication Start
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/auth_start.html
Processes URL parameters to set up authentication state and redirect URIs. Used for both mock OAuth testing and initiating Google OAuth flow.
```javascript
const params = new URLSearchParams(window.location.search); const mockOAuth = params.get('mockOAuth'); const authId = params.get('authId'); const method = params.get('oauthRedirectMethod'); const redirectUrl = params.get('hostRedirectUrl'); const redirect_uri = params.get('redirect_uri'); const hostName = params.get('hostName'); const state = `{"authId":"${authId}","method":"${method}","hostName":"${hostName}"}`; if (redirectUrl) { sessionStorage.setItem('hostRedirectUrl', redirectUrl); } const getRedirectUri = () => { if (redirect_uri) { return redirect_uri; } else { const idx = window.location.href.lastIndexOf('/'); return `${window.location.href.slice(0, idx)}/auth_end.html`; } }; // Redirect to auth_end page if its mockOauth for testing if (mockOAuth === 'true') { window.location.href = getRedirectUri() + `?state=${state}&code=test_auth_code_1234`; } else { // Do actual google login const queryObj = { state, client_id: '1073583513214-oplf5k63msf7at9rcj68vbrh265803vo.apps.googleusercontent.com', response_type: 'code', access_type: 'offline', scope: 'email%20profile', }; const query = Object.entries(queryObj) .map(([k, v]) => `&${k}=${v}`) .join(''); window.location.href = `https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=${getRedirectUri()}${query}`; }
```
--------------------------------
### Example Official Release CDN Script Tag
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases
Example of how to include an official TeamsJS library release (version 2.18.0) using a script tag with integrity hash.
```html
```
--------------------------------
### Generate SSR App SSL Certificates Manually
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Manual steps to generate SSL certificates for the SSR Test App using mkcert, including installing mkcert, the local CA, and generating certificates for localhost.
```bash
# Install mkcert (if not already installed)
brew install mkcert # macOS
# or follow instructions at https://github.com/FiloSottile/mkcert
# Install the local CA
mkcert -install
# Generate certificates in the certificates directory
cd apps/ssr-test-app/certificates
mkcert localhost
# This creates localhost.pem and localhost-key.pem
```
--------------------------------
### Generate SSR App SSL Certificates Automatically
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Automated script to set up SSL certificates for the SSR Test App, including checking for mkcert installation and generating certificates.
```bash
# From the monorepo root
pnpm setup-ssr-app-cert
```
--------------------------------
### Run SSR App with HTTPS from Monorepo Root
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Command to start the SSR Test App with HTTPS enabled when run from the monorepo root directory.
```bash
# From monorepo root
pnpm start-ssr-app:https
```
--------------------------------
### Run SSR App with HTTPS from ssr-test-app Directory
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/ssr-test-app/README.md
Commands to start the SSR Test App with HTTPS enabled when run from the ssr-test-app project directory, differentiating between development and production modes.
```bash
# Or from the ssr-test-app directory
pnpm dev:https # for development
# or
pnpm start:https # for production (requires pnpm build first)
```
--------------------------------
### Asynchronous Function with Callback (Deprecated)
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture
This is an example of an outdated asynchronous function signature that uses callbacks. New API calls will be rejected if they use this pattern.
```TypeScript
export function getFoo(callback: (foo: Foo, sdkError: SdkError) => void): void
{…}
```
--------------------------------
### Build the Project
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
Build the entire project, including TeamsJS and all included apps, using pnpm.
```bash
pnpm build
```
--------------------------------
### Run Unit Tests
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
Execute unit tests for the project using pnpm.
```bash
pnpm test
```
--------------------------------
### Generate Bundle Analysis
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/tools/bundle-size-tools/bundle-analysis-app/README.md
Run this command to generate a webpack profile for bundle analysis.
```bash
pnpm webpack:profile
```
--------------------------------
### Clone the Repository
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
Clone the Microsoft Teams JavaScript client library repository to your local machine.
```bash
git clone https://github.com/OfficeDev/microsoft-teams-library-js.git
```
--------------------------------
### Build or Test from teams-js Directory
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
When working within the `packages/teams-js` directory, you can run build or test commands directly.
```bash
pnpm build
```
```bash
pnpm test
```
--------------------------------
### Generate Reference Documentation
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/README.md
Locally generate reference documentation for TeamsJS v2. The output will be in the `packages/teams-js/docs` directory.
```bash
pnpm run docs
```
--------------------------------
### Including Open Iconic Standalone
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Link the default stylesheet for using Open Iconic without a specific framework.
```html
```
--------------------------------
### Including Open Iconic with Foundation
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Link the Foundation-specific stylesheet to integrate Open Iconic with Foundation projects.
```html
```
--------------------------------
### Enable TeamsJS Logging
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Logging
Run this command in the browser console to enable the 'teamsJs' logging category. Note that this setting is case-sensitive and persists in local storage.
```javascript
localStorage.debug = 'teamsJs.*';
```
--------------------------------
### Including Open Iconic with Bootstrap
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Link the Bootstrap-specific stylesheet to use Open Iconic with Bootstrap projects.
```html
```
--------------------------------
### Standard JSDoc for Public Functions
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/Library-Architecture
This is the standard format for documenting exported functions. It includes a clear description, parameter details, and return value information.
```JavaScript
/**
* Brief, clear description of exactly what this function is intended to do and
* any side effects it might have (like showing UI to the user)
* @param One per parameter, describing what the parameter is used for
* @returns Brief, clear description of what the function returns.
*/
```
--------------------------------
### Moving APIs to App Namespace
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md
APIs previously in `publicAPIs` and `appInitialization` have been moved to the new `app` namespace. This includes initialization, context, theme change handlers, and notification functions.
```typescript
// Moved from publicAPIs to app namespace:
initialize
getContext
registerOnThemeChangeHandler
// Moved from appInitialization to app namespace:
notifyAppLoaded
notifySuccess
notifyFailure
notifyExpectedFailure
// Added to app namespace:
isInitialized
getFrameContext
```
--------------------------------
### Using Open Iconic with Foundation
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Use the `fi-icon-name` class on span elements to display icons when using Open Iconic with Foundation.
```html
```
--------------------------------
### Using Open Iconic Standalone
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Apply the `oi` class and use the `data-glyph` attribute to specify the icon name when using Open Iconic independently.
```html
```
--------------------------------
### Beta Release CDN URL Pattern
Source: https://github.com/officedev/microsoft-teams-library-js/wiki/TeamsJS-Releases
Use this URL pattern to reference beta TeamsJS library releases from the SDF CDN endpoint. Replace with the specific beta version.
```html
https://res-sdf.cdn.office.net/teams-js//js/MicrosoftTeams.min.js
```
--------------------------------
### Listen for Parent Window Messages
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/naa_childIframe.html
Sets up an event listener to receive messages from the parent window. It validates the origin and extracts default payloads for the child iframe.
```javascript
let defaultPayloadForBridge = '';
let defaultPayloadForTopWindow = '';
// Listen for messages from the parent window.
window.addEventListener('message', (event) => {
// Validate the origin if known
if (event.origin !== window.origin) return;
const data = event.data;
if (data.defaultPayloadForBridge) {
defaultPayloadForBridge = data.defaultPayloadForBridge;
}
if (data.defaultPayloadForTopWindow) {
defaultPayloadForTopWindow = data.defaultPayloadForTopWindow;
}
});
```
--------------------------------
### Moving APIs to Pages.Config Sub-capability
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md
APIs formerly in the `settings` namespace have been renamed and moved to the `pages.config` namespace. This includes handlers for configuration changes and getting/setting configuration.
```typescript
// Renamed and moved to pages.config namespace (formerly settings):
registerEnterSettingsHandler has renamed and moved to pages.config.registerChangeConfigHandler
getSettings has been renamed pages.config.getConfig
setSettings has been renamed pages.config.setConfig
```
--------------------------------
### Commit Message Format
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/CONTRIBUTING.md
Follow this format for commit messages to ensure clarity and consistency. Include a summary, detailed explanation, and issue tracking.
```console
Summarize change in 50 characters or less
Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.
If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.
Fix #42
```
--------------------------------
### Importing Teams JS SDK Core Namespace
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md
Demonstrates the new import convention for the Teams JavaScript client SDK, organizing top-level functions under a core namespace. This replaces the older `import * as ... from ...` syntax.
```typescript
import { core } from '@microsoft/teams-js';
```
--------------------------------
### Moving APIs to Pages.FullTrust Sub-capability
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md
APIs for full trust operations, such as entering and exiting fullscreen mode, have been moved from `privateAPIs` to the `pages.fullTrust` namespace.
```typescript
// Moved from privateAPIs to pages.fullTrust namespace:
enterFullscreen
exitFullscreen
```
--------------------------------
### Initialize Teams SDK and Notify Authentication Status
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/teams-test-app/src/public/externalOauth_end.html
This JavaScript function initializes the Microsoft Teams SDK and then notifies the Teams client of the authentication outcome (success or failure) based on URL parameters. It logs the process to the page.
```javascript
function appendLog(msg) {
const element = document.createElement('p');
element.textContent = msg;
document.getElementById('log').appendChild(element);
}
const params = new URLSearchParams(window.location.search);
const titleId = params.get('titleId');
async function callteamsJS() {
if (microsoftTeams) {
appendLog('successfully loaded microsoftTeams');
try {
await microsoftTeams.app.initialize();
if (titleId === 'testOauthFailureTitleId') {
microsoftTeams.authentication.notifyFailure('Failed');
appendLog('notifyFailure sent');
} else {
microsoftTeams.authentication.notifySuccess('Success');
appendLog('notifySuccess sent');
}
} catch (e) {
appendLog('Error calling teams js: ' + e);
}
} else {
appendLog('no microsoftTeams');
}
}
```
--------------------------------
### Coloring Icons with CSS
Source: https://github.com/officedev/microsoft-teams-library-js/blob/main/apps/blazor-test-app/wwwroot/css/open-iconic/README.md
Set the fill color for specific icons by applying a CSS rule to their unique class on the `