Edit

Share via

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

  • Article

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.

Note

An add-in that uses the unified manifest can be sideloaded on Office on Windows, Version 2304 (Build 16320.20000) or later. Currently, it can't be sideloaded on the web, Mac, or iPad.

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 the Teams Toolkit

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

  2. In Visual Studio Code, open Teams 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.

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. You can now work with your add-in.
  5. 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 the Teams Toolkit CLI (command-line interface)

  1. Manually create a zip package using the following steps.

    1. Open the unified manifest and scroll to the "icons" property. Note the relative path of the two image files.
    2. Use any zip utility to create a zip file that contains the unified manifest and the two image files. The image files must have the same relative path in the zip file as they do in the project. For example, if the relative path is "assets/icon-64.png" and "assets/icon-128.png", then you must include the "assets" folder with the two files in the zip package.
    3. If the folder contains other files, such as image files used in the Office ribbon, remove these from the zip package. It should have only the two image files specified in the "icons" property (in addition to the manifest in the root of the zip package).

  2. In the root of the project, open a command prompt or bash shell and run the following commands.

    npm install -g @microsoft/teamsapp-cli

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

  3. When you use the Teams 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 the "{GUID of the add-in}" with the GUID in the "id" property of the unified manifest.

    teamsapp uninstall -manifest-id {GUID of the add-in}