Create an add-in for Office It has become a very powerful way to extend Word, Excel, Outlook, PowerPoint, and other applications. Microsoft 365 without having to develop traditional desktop add-ins. These new add-ins are based on standard web technologies and the JavaScript API for Office, enabling the creation of modern, secure, and easy-to-deploy experiences across the organization.
In the following lines you will find a very complete guide about development tools, manifest types, available APIs, and deployment optionsintegrating official Microsoft documentation. The idea is that you can go from scratch to having a working add-in, understanding what each piece does and what technical decisions you need to make at each step.
What is a modern Office add-in and how is it structured?
Modern Office add-ins They rely on the Office add-ins platform, which is common to Word, Excel, PowerPoint, OneNote, Outlook, and Project, on desktop, web, and, in some cases, mobile. They all share the same basic architecture composed of two clearly differentiated parts.
The first piece is the manifesto of the complementThis file acts as the add-in's "identity card." It declares the metadata (ID, name, version, languages), which Office applications it can be used with, what permissions it needs, what commands it adds to the ribbon, what icons it uses, where the web application is hosted, and in what contexts it should be activated (for example, in Outlook, only for messages or appointments that meet certain rules).
The second piece is the web application This application provides the user interface and business logic. It consists of HTML, CSS, and JavaScript (or TypeScript) and runs within an Office HTML container (task pane, content add-in, or dialog box). From there, it uses the office.js library to read and write to the document, call external services, handle authentication, display dialog boxes, and perform any other typical tasks of a modern web app.
Tools for creating Office add-ins
There is no single way to start an add-in project. Microsoft offers several official toolsThese tools cater to different user profiles: from those who prefer Visual Studio templates to those who work daily with Node.js and Visual Studio Code. There are also third-party or more specialized tools, such as UI editors for VBA.
Yeoman generator for Office add-ins
The Yeoman generator for Office is probably the most flexible option for web developers. It allows you to create Node.js-based projects that you can edit with Visual Studio Code or your preferred publisher. The wizard guides you through a series of questions to choose the type of add-in (task pane, content add-in, custom functions, Outlook, etc.) and the target application.
With this generator you can create projects for Excel, OneNote, Outlook, PowerPoint, Project, Word, and custom Excel functions. Furthermore, it lets you choose between a simple stack with HTML, CSS and JavaScript/TypeScript or a React-based architecture, also in JavaScript or TypeScript, with the entire project structure already prepared.
Visual Studio for Office projects
If you move more comfortably in .NET environmentsVisual Studio includes specific templates for Office add-ins. These templates primarily cover Excel, Outlook, Word, and PowerPoint, creating a complete solution that includes the add-in manifest, the web app, and, optionally, associated backend projects.
The Visual Studio project It is also based on HTML, CSS, and JavaScript, but integrates with the classic Microsoft ecosystem.Integrated debugging, publishing, packaging, etc. It's a good choice when you're already working with enterprise solutions in Visual Studio and want to keep everything centralized in the same IDE.
Microsoft 365 Agents Toolkit and Office Add-ins Developer Kit
Microsoft 365 Agents Toolkit It's designed to go beyond traditional add-ins and create virtually any type of extension for the Microsoft 365 ecosystem, combining bots, Teams extensions, and add-ins. With this tool, you can generate Office add-in projects that fit within broader Microsoft 365 applications.
Office Add-ins Developer Kit It's a Visual Studio Code extension that greatly simplifies daily life. From within VS Code, you can create new add-in projects, load ready-to-test code samples, and manage the entire development lifecycle without leaving the editor. The extension is designed to work with both unified manifests and add-in-only manifests.
The manifesto: the heart of the add-in configuration
Each Office add-in is described by a manifest file This tells applications how to load it, what interface options to expose, and what permissions to require. There are two main manifest templates, and the choice between them determines how you can integrate your add-in with other Microsoft 365 extensions.
Types of manifesto: supplement only and unified manifesto
- Manifesto of only complement. It's the classic format for production Office add-ins in Excel, OneNote, Outlook, PowerPoint, Project, and Word. It's written in XML and focuses solely on describing the add-in, without mixing it with other types of applications.
- Unified Manifesto for Microsoft 365. The evolution of the manifest model in JSON format, historically used in Teams applications. This format allows different types of Microsoft 365 extensions—Office add-ins, Teams extensions, etc.—to be packaged into a single application.
The configuration logic is similar in both casesYou define a unique identifier (usually a GUID), the version, display name, description, supported languages, icons, permission types (for example, read or read/write documents), and the interface structure (tabs, groups, and ribbon buttons). You also specify the web application's launch URL and any additional settings, such as keyboard shortcuts in Excel or Word, trigger rules in Outlook, or the dimensions of panels and content add-ins.
Key elements declared in the manifesto
Addition basic metadataThe manifest must carefully detail how the add-in integrates into the Office experience. This includes branding images and ribbon command icons, which must be hosted on a server that allows caching (HTTP headers with Cache-Control: no-cache or similar for production).
Another critical aspect is safetyAll URLs pointing to the web application or add-in resources must use HTTPS. While some development scenarios allow HTTP or self-signed certificates, if you want to run the add-in in Office on the web or publish it on the Microsoft Marketplace, SSL is mandatory to avoid mixed content warnings and ensure data protection in transit.
If you plan to distribute your add-on through the Microsoft Marketplace, the manifest must include, In addition to the unique GUID, an accessible and valid technical support URL. Microsoft applies a series of validation guidelines where the consistency of the manifest data, the behavior of the add-in, and compliance with security and user experience requirements are reviewed.
Allowed domains and origins for Office.js
The manifesto also controls which domains can be navigated within the plugin panelIn Office on the web and the new Outlook for Windows, the task pane can load almost any URL. However, in desktop applications, the behavior is stricter: if the add-in tries to navigate to a domain other than the homepage domain, the URL opens outside the application, in a separate browser window.
To avoid that external jump on the desktopYou can explicitly list each additional domain you want to appear in the add-in window in the manifest. If the target is listed, it will open within the panel in both Office desktop and Office on the web; otherwise, on desktop, it will open in an external browser.
Interacting with documents using the Office JavaScript API
The add-in's web application communicates with the Office document. (or with the message in the case of Outlook) via the Office JavaScript API library, accessible through Microsoft's official CDN at https://appsforoffice.microsoft.com/lib/1/hosted/office.jsSimply reference this script in the section <head> from the page to be able to use the available types and methods.
Once the library is loaded, you have access to two complementary API models:
- Application-specific APIs.
- Common APIs.
Each model has been designed to cover different scenarios, although they can be combined in the same accessory depending on the needs.
Application-specific APIs
Application-specific APIs provide strongly typed objects These represent native entities of the specific Office application. For example, in Excel you have objects for worksheets, ranges, tables, and charts, which allow you to manipulate data in a structured and efficient way.
This model is based on batch operationsYou chain actions within a context and, when you're ready, synchronize the changes with Office. This way of working reduces the number of trips between the add-in and the application, significantly improving performance, especially in Office on the web.
Common APIs for shared features
Common APIs They focus on cross-cutting functionalities present in several applications: interface elements, dialog boxes, client settings, etc. This model uses callbacks instead of promises and, by design, each call performs a single operation against the application.
With common APIs you can, for example, display a pop-up dialog box, manage the configuration of an add-in on different hosts, or access certain capabilities of Outlook, PowerPoint, or Project that are not yet covered by application-specific APIs, depending on the use case.
Requirements sets and cross-platform compatibility
API compatibility is organized into requirement setsThese group specific API members under a version name. There are application-specific requirement sets, such as ExcelApi 1.7and other shared ones, such as DialogApi 1.1, which work where dialog box functionality is supported.
The add-in can check at runtime whether the Office application it's running under meets the necessary requirements. This allows you to tailor the experience or disable advanced features when the host doesn't meet the minimum requirements, instead of causing unexpected errors.
Explore the API with Script Lab
Script Lab is a free add-on It acts as a testing ground for the Office JavaScript API. It's installed from the Microsoft Marketplace and runs within applications like Excel or Word, allowing you to write and execute code snippets in real time on the current document.
Within Script Lab you have access to a library of ready-to-use examples that demonstrate various API capabilitiesYou can use these snippets as a basis for your own code, modify them, and instantly see the result in the document, which greatly speeds up the prototyping and testing phase of functionalities before incorporating them into your final plugin.
How to expand the Office user interface
One of the great advantages of add-ins is that they allow integrate the functionality directly into the Office interfaceso that the user doesn't feel like they are "leaving" the application. This is achieved by combining plugin commands and HTML containers such as task panels, content plugins, and dialog boxes.
- Add-in Commands They are used to add custom tabs, new groups, and additional buttons or menus to the Office ribbon.
- HTML containers (task panes, content add-ins and dialogs) act as a surface on which to display the add-in's own interface.
In a typical scenario, you might have a command that adds a group with an "Analyze Data" button in Excel; when pressed, a task pane opens on the right with your web app, which analyzes the selected range, calls a machine learning service, and returns the results by highlighting cells or creating charts using Excel's specific API.
Create a task pane add-in with Yeoman (Word example)
To put all these concepts into practiceIt's helpful to see how to build a task pane add-in in practice using Yeoman's generator, for both Word and Outlook. Although the interface details change between applications, the project structure and workflow are very similar.
Development environment prerequisites
Before generating the projectYou need to have the latest LTS version of Node.js installed, which can be downloaded from the official website. Once installed, globally install Yeoman and the Office generator using the command npm install -g yo generator-officeFinally, make sure you have Office linked to a Microsoft 365 subscription that includes Office on the web, as you'll be testing the add-in on both desktop and browser.
Creating a Word add-in with a task pane
The first step is decide the type of manifesto which you want to use depending on whether you intend to combine your add-in with other extensions in a single app or not. Once you've made your decision, you run yo office in the working directory.
On interactive assistantYou can, for example, choose a project type, assign a name like "My Office Add-in," and select Word as the target client application. When finished, the generator creates the project folder, installs the Node dependencies, and gets everything ready to go.
Within the solution you will find the manifest file (manifest.json o manifest.xml) in the root, which defines the plugin configuration; the file ./src/taskpane/taskpane.html with the task pane markup; the CSS in ./src/taskpane/taskpane.css; and the code that calls the Office API in ./src/taskpane/taskpane.ts o .jsdepending on whether you chose TypeScript or JavaScript.
To test the add-in in desktop WordYou just need to navigate to the project's root folder (cd "My Office Add-in"and execute npm startThis command launches the local web server and starts Word with the add-in already loaded in sideloading mode. If you prefer to try it in Word on the web, you can use a command like this: npm run start -- web --document {url}, replacing the URL with that of a document stored in OneDrive or SharePoint.
Development server and dependency management
During development it is common that npm install It might fail during the automatic step that Yeoman executes, especially if there are conflicts with dependency versions. In those cases, simply go into the project folder and launch npm install manually to solve it.
If obsolete dependency warnings appearYou can rely on the tool npm-check-updates, installing it with npm i -g npm-check-updates, running ncu -u to update version ranges in package.json and completing the process with a new npm installMany of these warnings are not critical, but it is good practice to review them periodically to keep the project healthy.
To stop the development server and uninstall the plugin in sideloading mode, you can run npm stop in the root directory. If you have previously uploaded the add-in manually (for example, by uploading the manifest to Office on the Web), you will also need to remove it manually from the corresponding administration interface.
From the basic structure of an add-in and development tools (Yeoman, Visual Studio, Agents Toolkit, Script Lab) to the role of the manifest, JavaScript APIs, security controls, and deployment options (local, Marketplace, centralized deployment, or via providers like Qlik), you have a fairly complete map to decide what type of add-on you need, how to build it, and how to put it in the hands of your users without technical surprises.