Word Add-in — Best Practice Sources

1. Platform overview & getting started

• Office Add-ins platform overview — canonical entry point. Web-technology add-in model, supported hosts, runtime sandbox.
• Beginner's guide to Office Add-ins — Microsoft's curated learning path for someone with zero prior experience.
• Build your first Word task pane add-in — the Yo Office hello-world.
• Tutorial: Create a Word task pane add-in — long-form tutorial covering insert/replace ranges, paragraphs, images, content controls, tables.
• Word add-ins overview — Word-specific programming model and capability survey.

2. Word JavaScript API reference

• Word JavaScript API overview — root index, Common vs application-specific.
• Word JavaScript object model in Office Add-ins — explains Word.run, proxy objects, load/sync semantics.
• Using the application-specific API model — defines RequestContext, batched execution, property loading.
• word package (API index) — flat index of every Word.* class. Bookmark this.
• Word.RequestContext — root of document, application, sync(), trackedObjects.
• Word.Document · Word.Body · Word.Range · Word.ContentControl — the four most-cited type pages.
• Word JavaScript API requirement sets — authoritative matrix of which APIs are available on which Word host/version.

3. Manifest (XML & unified)

• Office Add-ins manifest — top-level hub.
• Office Add-ins with the add-in only manifest (XML) — canonical reference for the legacy XML manifest.
• Office Add-ins with the unified app manifest for Microsoft 365 — JSON manifest. GA for Outlook, preview for Word/Excel/PowerPoint as of Apr 2026.
• M365 app manifest schema reference — JSON schema reference. Currently m365-app-1.26.
• Compare add-in only vs unified manifest — side-by-side mapping.
• Convert an add-in to use the unified manifest — uses office-addin-manifest-converter.

4. Authentication & identity

• Overview of authentication and authorization in Office Add-ins — names the three paths: legacy SSO, NAA, dialog fallback.
• Enable SSO with Nested App Authentication (NAA) — the current 2025/2026 recommended path. MSAL.js createNestablePublicClientApplication. Supersedes getAccessToken.
• Enable legacy Office single sign-on — the old Office.auth.getAccessToken + OBO flow. Note "legacy" in the title — formally deprecated.
• Office.Auth interface — reference for Office.auth.getAccessToken.
• Use the Office dialog API — displayDialogAsync is the always-works fallback.
• Authenticate via the Office dialog API — canonical pattern for an interactive MSAL/OAuth popup.
• NAA + Outlook legacy tokens deprecation FAQ — current timeline/status.

5. Performance & best practices

• Resource limits and performance optimization — canonical perf page. Batching, context.sync(), load pruning, payload ceilings.
• Best practices for developing Office Add-ins — UX, responsiveness, error handling, throttling.
• Avoid context.sync in loops (correlated objects pattern) — the single most important perf anti-pattern doc.
• OfficeExtension.LoadOption — property-pruning reference.
• Task panes in Office Add-ins — sizing (320 px target), layout, design guidance.

6. Project generators & scaffolds

• Yeoman generator-office ("Yo Office") — scaffolds task-pane / content / custom-function add-ins. Still the default. ~934 ★, v3.0.2 (mid-2025). Webpack-based.
• Microsoft 365 Agents Toolkit — forward-looking path. Successor to Teams Toolkit. Recommended for new add-ins, especially with the unified manifest. templates-vs@18.6.0 (Mar 2026).
• Agents Toolkit for Office add-ins (Learn) — onboarding doc.
• Office-Addin-TaskPane-React — canonical React template Yo Office pulls from.
• ExtraBB / Office-Addin-React-Vite-Template (community) — most-cited Vite + React 18 + TS starter. No official Microsoft Vite scaffold exists yet.
• Set up your dev environment — supported toolchains. VS "Office Add-in" project type is being deprecated in VS 2026.

7. CLI tools (npm)

All maintained inside OfficeDev/Office-Addin-Scripts by the Office team.

• office-addin-debugging — orchestrates dev-server + sideload + debugger. v6.0.6 (Dec 2025).
• office-addin-manifest — parse / modify / validate XML and unified manifests. ~v2.0.x.
• office-addin-dev-certs — generates and trusts the localhost dev CA cert. Required for first npm start.
• office-addin-cli — thin wrapper. v2.0.6.
• office-addin-mock — in-memory mock of the Office.js proxy-object model for unit tests. v3.0.6.
• office-toolbox — unmaintained (last activity 2019). Avoid for new projects.

8. Bundlers, IDEs, linting, local HTTPS

• Webpack 5 — what Yo Office and Office-Addin-TaskPane-React ship. Reference implementation for manifest copy, asset injection, Office.js CDN reference, source maps.
• vite-plugin-office-addin — community Vite plugin. No Microsoft endorsement.
• Microsoft 365 Agents Toolkit VS Code extension — primary VS Code extension for scaffolding, F5 debug, manifest validation.
• Microsoft Office Add-ins Development Kit — lightweight debugger/attach extension.
• @types/office-js — DefinitelyTyped definitions. v1.0.529 (Apr 2026), updated nearly daily.
• eslint-plugin-office-addins — catches common Word.run / context.sync mistakes. v4.0.6.
• eslint-config-office-addins — ready-to-extend config.
• WSL / Codespaces caveat — Word desktop runs on the Windows host and reads the Windows cert store. Re-run office-addin-dev-certs install from a Windows shell. In Codespaces, port-forward 3000 to a trusted loopback locally.

9. Sample repositories

• OfficeDev / Office-Add-in-samples — 972 ★, actively maintained. Canonical Microsoft sample set: Word hello-world, template import, citations, SSO, Graph, Blazor WASM. Most samples ship a manifest-configurations/unified subfolder.
• OfficeDev / office-js-docs-pr — source markdown for learn.microsoft.com. Read snippets here before trusting rendered docs.
• OfficeDev / office-js — issue tracker + type-definition source. File bugs here.
• PnP / PnP-OfficeAddins — historical PnP community repo, largely merged into OfficeDev/Office-Add-in-samples.

10. Sideloading

• Sideload Office Add-ins on Mac — drop manifest into ~/Library/Containers/com.microsoft.Word/Data/Documents/wef. Finder is the only supported path.
• Sideload from a network share (Windows shared folder catalog) — SMB share + Trust Center → Trusted Add-in Catalogs.
• Sideload to Office on the web — Insert → Office Add-ins → Upload My Add-in.
• Sideload add-ins that use the unified manifest — ship as a .zip; requires m365 CLI / office-addin-debugging.

11. Centralized Deployment

• Deploy and manage Office Add-ins through Integrated Apps — recommended path: M365 admin center → Settings → Integrated apps.
• Requirements to use centralized deployment — Exchange Online + OAuth mailboxes, Entra-joined tenant, Exchange Admin role. Propagation up to 24 hours. (Updated 2026-03-19.)
• Centralized Deployment FAQ — SKU eligibility, nested-group limitations, GCC fallback.
• Deploy Office Add-ins in the M365 admin center — step-by-step UI walkthrough.
• Manage your apps in the Teams admin center — required for cross-surface "Apps for M365" packages.

12. AppSource publishing

• Publish your Office Add-in to Microsoft Marketplace — Partner Center, manifest validation, store listing.
• Submit to AppSource via Partner Center — submission wizard. Validation review 3-5 business days for clean submissions.
• M365 app publishing checklist — pre-submission gate.
• Top 5 AppSource validation errors (Dec 2023, devblog) — recurring rejection causes.
• Marketplace submission FAQ — resubmission cadence, certification policy versioning.

13. Intune & mass deployment

• Add Microsoft 365 Apps to Windows Devices Using Intune — baseline.
• Create a settings catalog policy in Intune — modern path for pushing wef\trustedcatalogs reg settings.
• Settings catalog walkthrough (replaces GPO) — maps legacy Trusted Add-in Catalogs to Intune CSP. Reg path: HKCU\Software\Policies\Microsoft\Office\16.0\WEF\TrustedCatalogs\<id> with Flags=1.
• M365 Apps for Enterprise security baseline — add-in / macro hardening reference.

14. Version management & lifecycle

• Office Add-ins manifest <Version> rules — semver. Bumping is mandatory for any manifest change to propagate.
• Troubleshoot user errors with Office Add-ins — cache locations. Web bundle hot-reloads are immediate; manifest changes require store/admin re-push.
• office-js#1048 — manifest <Version> auto-update behavior — AppSource auto-refresh within hours; sideloaded URL installs need re-add.
• Manage both unified and add-in only manifests in parallel — A/B pattern during migration.
• Microsoft Q&A — when manifest updates auto-reach users — permission/scope changes trigger re-consent; cosmetic changes do not.

15. Telemetry & monitoring

• Debug your add-in with runtime logging — enable on Word desktop via HKCU\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\RuntimeLogging; on Mac via defaults write com.microsoft.Word CEFRuntimeLoggingFile.
• Debug Office Add-ins overview — what Office gives you for free vs what you instrument.
• Application Insights OpenTelemetry overview — standard SDK for instrumenting the task-pane bundle.
• Application Insights telemetry data model — requests, dependencies, exceptions, custom events.
• Overview of diagnostic log files for Office (Support) — File → Options → Trust Center → Privacy Options → Diagnostic data.
• Enable M365 Apps for Enterprise ULS logging — deeper Office host logging.

16. Real-world Word add-ins

Worth studying for architectural inspiration. Most are cloud-only (no desktop client dependency).

• Mendeley Cite (AppSource) — reference manager. Works in Word desktop, web, and iPad without legacy Mendeley Desktop. Cloud-only architecture reference.
• DocuSign Template Assistant (AppSource) + DocuSign + Word integration page — ribbon-integrated send/sign flow.
• Grammarly for Microsoft Word (AppSource) — Office.js add-in pairing with the cloud grammar service.
• "Get more done in less time with these 10 popular Word add-ins" — Microsoft's roundup naming Grammarly, Wordtune, Pickit, Pexels, Mendeley, Woodpecker, etc.

17. Compliance & privacy

• M365 App Compliance Program overview — three tiers: Publisher Attestation, M365 Certification, ACAT-automated.
• M365 Certification framework — control families (app security, ops security, data handling/privacy, external compliance like SOC2/ISO 27001).
• User Guide for M365 App Compliance Program — Partner Center walkthrough for ISVs.
• Automate M365 Certification with ACAT — Azure-portal service that auto-collects evidence.
• App Compliance Program landing — publisher-facing entry point.

18. Word.run / RequestContext model (deep dive)

• Using the application-specific API model — proxy objects, load queueing, why sync() is the only way JavaScript state meets document state.
• Word.RequestContext reference (preview) — exact surface of context, trackedObjects, sync(), document.
• OfficeExtension.LoadOption — select / expand / top / skip shape.
• Correlated objects pattern — batching idiom that keeps sync-per-iteration from dominating latency.
• Resource limits and performance optimization — payload ceiling lives here. Excel-on-the-web is 5 MB, not 1 MB as commonly misremembered.

19. Performance pitfalls

• Best practices for developing Office Add-ins — minimize sync calls, load only what you read, untrack aggressively.
• OfficeExtension.TrackedObjects — why Range/ContentControl references held across syncs must be tracked, and why forgetting to untrack() spins desktop Word.
• office-js#6312 — memory leak in getSelection — repeated Word.run + selection loads climb memory indefinitely. Canonical "my add-in is leaking" repro.
• office-js#3982 — Word API near-instant on Windows, slow on Mac — Mac per-call overhead that turns chatty code into a progress-bar disaster.
• Excel JavaScript API performance optimization — Excel-targeted but the sync-batching, suspendApiCalculationUntilNextSync, untrack advice applies verbatim to Word.

20. Selection & range gotchas

• Word.Range — enumerates getRange("Start"|"End"|"Before"|"After"|"Content"|"Whole") variants and which collapse.
• Word.Body — body.insertHtml only accepts Replace|Start|End. Reason Before/After throw on a Body but work on a Range.
• Word.ContentControl — "CCs are ranges plus a wrapper" mental model.
• office-js#1516 — InsertLocation.replace behaves like start — leaves residual text. Classic gotcha.
• office-js#2907 — contentControl.insertHtml broken after re-opening — round-trip breaks when a saved+reopened doc re-parses CC ranges.
• office-js#5628 — range.insertField in CC needs .select() first — selection state secretly affects "range" operations.

21. Cross-platform differences

• Browsers and webview controls used by Office Add-ins — definitive matrix: WebView2 on Windows, WKWebView on Mac/iOS, iframes on the web. Cookie/storage implications.
• Check for API availability at runtime — Office.context.requirements.isSetSupported("WordApi", "1.5"). The only clean way to branch per-host.
• Understanding platform-specific requirement sets — Word desktop-only and Word online-only requirement sets.
• caniwebview.com — Cookies — third-party reference for WebView2 vs WKWebView, especially ITP on iOS.
• WebView2Feedback#644 — sharing cookies across WebView2 instances — taskpane and dialog don't share a cookie jar even on the same machine.

22. Authentication gotchas

• Troubleshoot legacy Office SSO — decoder ring for the silent-failure modes (13000-series error codes).
• New Nested App Authentication for Office Add-ins (devblog) — why the Exchange-token pattern is dead.
• office-js#4712 — Outlook NAA GA questions — conditional-access policies, multi-tenant vs single-tenant, redirect URI rules.

23. Lifecycle & shared runtimes

• Runtimes in Office Add-ins — three flavors (UI-less, JS-only, browser).
• Configure a shared runtime — manifest changes; what shared runtime buys you (state across taskpane close, ribbon-button handlers sharing globals).
• Tips for using the shared JavaScript runtime (devblog) — lifecycle-kills enumerated.
• office-js-docs-pr#1954 — shared runtimes and multiple taskpanes — community thread fills doc gaps.
• Persist add-in state and settings — why Office.context.document.settings beats localStorage for state surviving host restarts.

24. Manifest pitfalls

• How to find the proper order of manifest elements — why "invalid child" is usually actually an ordering error.
• VersionOverrides reference — TaskPaneApp supports only v1.0; MailApp supports v1.0 and v1.1. Common Word-vs-Outlook copy-paste trap.
• SourceLocation reference — must be HTTPS, must return 200, redirects cause failures.
• "Office Add-in manifest updates — deployment timing and URL issues" (Cameron Dwyer) — MVP blog on real-world propagation delay and cache issues.

25. Insertion fidelity (insertText / insertHtml / insertOoxml)

• Use Office Open XML in Word add-ins — when insertOoxml is the only option and how to strip flat-OPC envelopes.
• "Tips and tricks for Word add-in development" (Tim van de Looy) — engineer's writeup of insertText vs insertHtml vs insertOoxml tradeoffs, with style-inheritance caveats.
• office-js#5491 — insertOoxml not reflecting style changes — existing target-doc styles win over OOXML-supplied definitions.
• office-js#5381 — insertOoxml not updating numbering but styles — list numbering is the most fragile OOXML round-trip case.
• office-js#4684 — insertOoxml may not preserve numbering style on the web — desktop vs web fidelity drift.
• office-js#2606 — table corruption on insertOoxml replace into CC with table — workaround: delete() + insertOoxml("End").

26. Modern features (Copilot, Smart Alerts, custom functions, event-based activation)

• Combine Copilot Agents with Office Add-ins (preview) — pair a declarative Copilot agent with a Word/Excel/PowerPoint add-in so Copilot can invoke add-in JS.
• Declarative agents for Microsoft 365 Copilot — upstream Copilot extensibility model.
• Create custom functions in Excel — JS-defined worksheet functions, streaming, data types.
• Activate add-ins with events — background activation (OnNewMessageCompose, OnDocumentOpened) — runs without a taskpane, requires shared runtime.
• Handle OnMessageSend and OnAppointmentSend with Smart Alerts — Outlook Smart Alerts model.

27. Migration & deprecation notes

• VSTO add-in developer's guide to Office Web Add-ins — Microsoft's official "coming from COM/VSTO" path.
• Tutorial: Share code between a VSTO Add-in and an Office Add-in — practical hybrid-migration pattern.
• Microsoft Edge WebView2 and Microsoft 365 Apps — shift from Trident/EdgeHTML to Chromium-based WebView2.
• Runtimes manifest element — declares a minimum Chromium/Trident runtime. Mechanism to drop IE/EdgeHTML support.

28. Cross-cutting findings

The recurring "if you only learn ten things" insights from the four research passes.

Related

• Word Add-in — the implementation reference for Hugo's specific add-in (architecture, filter dimensions, chat dispatcher, tool registry)
• API Reference — every JSON endpoint Hugo exposes

Compiled by parallel research agents on 2026-04-13. Source markdown: office-addins/word/docs/sources.md. Update by re-running the same four research passes against current Microsoft Learn URLs whenever the docs are restructured.