microsoft-teams

microsoft-teams Best Practices

Microsoft Teams is the backbone of enterprise collaboration. To build high-quality, maintainable, and performant applications, adhere to these definitive guidelines.

1. Code Organization and Structure

Always start with a standardized project structure and leverage modern tooling.

✅ Use Microsoft 365 Agents Toolkit for Project Scaffolding

The Microsoft 365 Agents Toolkit (formerly Teams Toolkit) provides the official project structure, linting rules, and CI/CD pipelines. It's the fastest way to a compliant and maintainable app.

❌ BAD: Manual project setup, inconsistent file organization.

// Don't manually create files and folders.
// This leads to inconsistent project structures.
// src/components/MyComponent.tsx
// src/api/teamsApi.ts
// ...

✅ GOOD: Generate with the toolkit.

# Use the VS Code extension or CLI
# This ensures a consistent, maintainable structure
# and pre-configured build/deploy scripts.
npm install -g @microsoft/teamsfx-cli # Or use the VS Code extension
teamsfx new --app-name my-teams-app --capabilities tab,bot

✅ Prefer TypeScript for All Development

TypeScript is mandatory for type safety, better tooling, and improved code quality.

❌ BAD: JavaScript for Teams app logic.

// myBotLogic.js
function handleMessage(context, message) {
    // No type checking, prone to runtime errors
    if (message.text.startsWith('/hello')) {
        context.sendActivity(`Hello ${context.activity.from.name}!`);
    }
}

✅ GOOD: TypeScript with explicit types.

// myBotLogic.ts
import { TurnContext, Activity } from 'botbuilder';

export async function handleMessage(context: TurnContext, activity: Activity): Promise<void> {
    if (activity.text?.startsWith('/hello')) {
        await context.sendActivity(`Hello ${activity.from?.name || 'there'}!`);
    }
}

2. Common Patterns and Anti-patterns

Adopt established patterns for UI, interaction, and data handling.