Sideload Office Add-ins that use the unified manifest for Microsoft 365

The process of sideloading an add-in that uses the Unified manifest for Microsoft 365 varies depending on the tool you want to use and on how the add-in project was created.

Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)

Use the process described in Sideload with a system prompt, bash shell, or terminal.

Sideload with Microsoft 365 Agents Toolkit

1. First, make sure Office desktop application that you want to sideload into is closed.

2. In Visual Studio Code, open Agents Toolkit.

3. Required for Outlook only: in the ACCOUNTS section, verify that you're signed into Microsoft 365.

4. Select View | Run in Visual Studio Code. In the RUN AND DEBUG dropdown menu, select one of these options as appropriate for your add-in.

   • Excel Desktop (Edge Chromium)
   • Outlook Desktop (Edge Chromium)
   • PowerPoint Desktop (Edge Chromium)
   • Word Desktop (Edge Chromium)

5. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then the desktop version of the Office application that you selected opens. You can now work with your add-in. For an Outlook add-in, be sure you're working in the Inbox of your Microsoft 365 account identity.

6. To stop debugging and uninstall the add-in, select Run | Stop Debugging in Visual Studio Code. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

   Note

   If the preceding step seems to have no effect, uninstall the add-in by opening a TERMINAL in Visual Studio Code, and then complete the uninstall step — the last step — of the section Sideload with a system prompt, bash shell, or terminal.

Sideload with a system prompt, bash shell, or terminal

1. First, make sure the Office desktop application that you want to sideload into is closed.
2. Open a system prompt, bash shell, or the Visual Studio Code TERMINAL, and navigate to the root of the project.
3. The command to sideload the add-in depends on when the project was created. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run npm run start:desktop; otherwise, run npm run start. The project builds and a Node dev-server window opens. This process may take a couple of minutes then the Office host application (Excel, Outlook, PowerPoint, or Word) desktop opens.
4. On some versions of Office, the add-in may not fully activate. For example, the add-in's buttons may not appear on the ribbon. If this happens, select the Add-ins button on the Home ribbon. On the flyout that opens, select the add-in. This completes the installation.
5. You can now work with your add-in.
6. When you're done working with your add-in, make sure to run the command npm run stop. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

Sideload other NodeJS and npm projects

There are two tools you can use to sideload.

Sideload with the Office-Addin-Debugging tool

1. To sideload the add-in, run the following command. This command puts the unified manifest and the two icon image files that are referenced in the manifest's "icons" property into a zip file and sideloads it to the Office application. It also starts a server in a separate NodeJS window to host the add-in files on localhost. For more details about this command, see Office-Addin-Debugging.

   npx office-addin-debugging start <relative-path-to-unified-manifest> desktop
   

2. When you use office-addin-debugging to start an add-in, always stop the session with the following command. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

   npx office-addin-debugging stop <relative-path-to-unified-manifest>
   

Sideload with Microsoft 365 Agents Toolkit CLI (command-line interface)

1. Create a zip package. See Manually create the add-in package file.

2. In the root of the project, open a command prompt or bash shell and run the following command to install the Agents Toolkit CLI.

   npm install -g @microsoft/m365agentstoolkit-cli
   

3. Run the following command to sideload the add-in.

   atk install --file-path <relative-path-to-zip-file>
   

   Important

   This command returns some information about the add-in including an autogenerated title ID as shown in the following example.

   

   You'll need this title ID to end the sideloading and debugging session. It is recorded on Windows computers in the following Registry key:

   HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\OutlookSideloadManifestPath\TitleId

   The string "Outlook" is in the key name for historical reasons, but it applies to any add-in installed with the Agents Toolkit CLI.

   Only the most recent add-in installed with the CLI is recorded. If you sideload an add-in with the CLI before you have uninstalled an earlier add-in you installed with the CLI, then there is no record of the earlier add-in's title ID in the Registry. So, we recommend that you also save it in a text file in the root of the project and name the file TitleID.txt on both Mac and Windows computers.

4. When you use the Agents Toolkit CLI to start an add-in, always stop the session with the following command. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. Replace "{title ID}" with the title ID of the add-in including the "U_" prefix; for example, U_90d141c6-cf4f-40ee-b714-9df9ea593f39.

   atk uninstall --mode title-id --title-id {title ID} --interactive false
   

   Important

   The documentation for the uninstall command describes a way to use the add-in's manifest ID instead of the title ID. Due to a bug in an API that the CLI calls, this option doesn't currently work. You must use the uninstall command given above and you must include the --interactive false option.

Sideload through the Teams app store

Add-ins that use the unified manifest can be manually sideloaded through the Teams app store, even if they have no Teams-related functionality. The steps are as follows.

1. Create an app package manually if it hasn't already been created by a tool. See Manually create the add-in package file.

2. Close all Office applications, and then clear the Office cache following the instructions at Manually clear the cache.

3. Open Teams and select Apps from the app bar, then select Manage your apps at the bottom of the Apps pane.

4. Select Upload an app in the Apps dialog, and then in the dialog that opens, select Upload a custom app.

5. In the Open dialog, navigate to, and select, the app package.

6. Select Add in the dialog that opens.

7. When you're prompted that the app was added, don't open it in Teams. Instead, close Teams.

8. The next task is to start a local web server that hosts your project's HTML and JavaScript files. How you do this depends on several factors including the folder structure of your project, the tools you use, such as a bundler, task manager, server application, and how you have configured those tools. The following instruction applies only to projects that meet the following conditions.

   • There's a webpack.config.js file in the root of the project that is similar to the ones in add-in projects that are created with the Yeoman Generator for Office Add-ins or Microsoft 365 Agent Toolkit.

   • There's a package.json file in the root of the project similar to the ones created by the same two tools and the file has a "scripts" section with the following script in it.

     "dev-server": "webpack serve --mode development"
     

9. In a command prompt or Visual Studio Code TERMINAL in the root of the project, run npm run dev-server to start the server on localhost.

10. Open the Office application that the add-in targets. Wait until the add-in has loaded. This may take as much as two minutes. Depending on your version of Office, ribbon buttons and other artifacts may appear automatically. In some versions, you need to manually activate the add-in: Select the Add-ins button on the Home ribbon, and then in the flyout that opens, select your add-in. It will have the name specified in the "name.short" property of the manifest.

Manually create the add-in package file

When the unified manifest is used, the unit of installation and sideloading is a zip-formatted package file. This file is usually created for you by the tools you use to create and test your add-in, but there are scenarios in which you create it manually. To do so, use any zip utility to create a zip file that contains the following files.

• The unified manifest, which goes in the root of the zip file.
• The two image files referenced in the "icons" property of the manifest.
• Any localization files that are referenced in the "localizationInfo" property of the manifest.
• Any declarative agent files that are referenced in the "copilotAgents" property.
• Any second-level supplementary files. For example, declarative agent configuration files sometimes reference second-level supplementary files, such as plugin configuration files. These should be included too.

To maximize compatibility with Microsoft 365 development tools, we recommend that you keep the files that will be included in the package in a folder called appPackage in the root of your project, and that you put the package file in a subfolder named build in the appPackage folder.

The following are examples of the recommended structure. The structure inside the \build\appPackage.zip file must mirror the structure of the appPackage folder, except for the build folder itself.

\appPackage
    \assets
        color.png
        outline.png
    \build
        appPackage.zip
    manifest.json

\appPackage
    \agents
        myAgent.json
        \plugins
            myPlugin.json
    \assets
        color.png
        outline.png
    \build
        appPackage.zip
    \languages
        fr-FR.json
        es-MX.json
    manifest.json