botbuilder-js

botbuilder is the core Node.js package of the Bot Framework SDK for JavaScript, a monorepo of libraries for building enterprise-grade conversational bots that run across channels like Microsoft Teams, Direct Line, and any Bot Framework-connected client. It provides the adapter layer (BotFrameworkAdapter and the newer CloudAdapter), a middleware pipeline modeled on Express/Restify, and a TurnContext abstraction that normalizes activities across channels so bot logic doesn’t need to know which surface it’s running on.

Beyond the core adapter, the package bundles channel service routing, Teams-specific activity handling and helpers, SharePoint activity handling, skills support for bot-to-bot delegation, streaming transport clients, and transcript storage. It’s built to compose with the wider monorepo’s sibling packages — botbuilder-dialogs for guided conversation flows, botbuilder-ai for LUIS/QnA Maker integration, and botbuilder-azure(-blobs/-queues) for state and storage — while working standalone for teams that just need the adapter and middleware layer.

What You Get

• BotFrameworkAdapter / CloudAdapter - the HTTP-facing adapter that authenticates incoming activities, manages the connector client, and dispatches to your bot’s turn handler.
• Middleware pipeline - an Express-like use() chain for cross-cutting concerns (logging, state persistence, translation) that runs before your bot logic on every turn.
• TeamsActivityHandler & teamsInfo helpers - typed handlers and utilities for Teams-specific events (task modules, message extensions, file consent, meeting events).
• SharePointActivityHandler - dedicated activity handler and SSO token-exchange middleware for bots embedded in SharePoint.
• Skills & ChannelServiceHandler - infrastructure for bot-to-bot delegation (skills) and implementing the Bot Framework channel/skill service contracts.
• FileTranscriptStore - file-based conversation transcript persistence for auditing and replay.
• Streaming transport client - StreamingHttpClient and TokenResolver for the named-pipe/streaming connection used by some channels instead of plain HTTP.

Common Use Cases

• Enterprise Teams bots - a company builds an internal helpdesk or HR bot using TeamsActivityHandler plus task modules and message extensions.
• Omni-channel support bot - a single bot logic layer is deployed once and reached from Teams, Direct Line, and other channels via the same adapter and TurnContext abstraction.
• Bot-to-bot delegation - a parent bot delegates specialized sub-tasks (e.g. booking, FAQ) to skill bots using the skills infrastructure and ChannelServiceHandler.
• SharePoint-embedded assistant - an internal SharePoint site embeds a bot using SharePointActivityHandler with SSO token exchange for seamless auth.
• Migrating from classic to cloud auth - existing BotFrameworkAdapter bots move to CloudAdapter to adopt the newer Azure AD-based authentication model.

Under The Hood

Architecture The package sits one layer above botbuilder-core in the monorepo’s dependency graph: botbuilder-core defines TurnContext, the middleware/use() pipeline, and the base Activity/BotAdapter abstractions, while botbuilder-js’s botbuilder package supplies the concrete, channel-facing adapters (BotFrameworkAdapter for the legacy auth model, CloudAdapter built on botframework-connector and Azure identity libraries for the current model) plus higher-level handlers layered on top of TurnContext — TeamsActivityHandler, SharePointActivityHandler, ChannelServiceHandler for skill/channel service contracts, and a streaming transport client for channels that use a persistent connection instead of per-turn HTTP. Because every handler and middleware step receives the same TurnContext, swapping the adapter (BotFrameworkAdapter vs CloudAdapter) or channel does not require touching bot logic — the abstraction that would break the most if changed is TurnContext itself, since every downstream package depends on its shape.

Tech Stack Written in TypeScript, compiled via tsc -b project references across the Yarn workspace monorepo, with tsup used to vendor a couple of ESM-only dependencies (filenamify, chai) as CommonJS so the package can stay CJS-first, and downlevel-dts producing TypeScript 3.4-compatible type definitions for consumers on older compilers. Runtime dependencies include @azure/msal-node and @azure/core-rest-pipeline for the CloudAdapter’s Azure AD authentication, axios for HTTP, zod for runtime validation, dayjs for date handling, and htmlparser2/fs-extra/uuid as supporting utilities. api-extractor tracks the package’s public API surface for compatibility checks, and the monorepo is orchestrated with wsrun across dozens of interdependent workspace packages.

Code Quality Each source module has a corresponding Mocha/Chai test file (botFrameworkAdapter, cloudAdapter, channelServiceHandler, channelServiceRoutes, teams/, skills/, streaming/* all have dedicated .test.js suites), coverage is collected with nyc, and CI runs the suite via GitHub Actions (badges for both Windows and Linux bot functional tests plus browser functional tests) with Coveralls tracking coverage trend. Linting uses a flat ESLint config shared across the monorepo. Error handling favors typed, purpose-built error classes such as StatusCodeError over generic throws.

API Design The adapter/middleware model directly mirrors Express and Restify, which keeps the learning curve low for Node.js web developers even though the domain (multi-turn, multi-channel conversation) is unusual. TurnContext gives a single consistent object to read/reply to activities regardless of channel, and CloudAdapter’s introduction simplified authentication setup compared to the original BotFrameworkAdapter. The API surface is large due to the number of channel-specific handlers and helpers (Teams, SharePoint, skills), which adds surface area a newcomer has to navigate even though any single integration only touches a small slice of it.