[All Hosts] (devx) sideloading changes (#5297)

Rick-Kirkham · samantharamon · web-flow · commit a76816c2f146 · 2025-07-25T13:27:53.000-07:00
* [All Hosts] (devx) sideloading changes

* several minor fixes

* fix links

* Apply suggestions from code review

Co-authored-by: Sam Ramon &lt;15154970+samantharamon@users.noreply.github.com&gt;

---------

Co-authored-by: Sam Ramon &lt;15154970+samantharamon@users.noreply.github.com&gt;
diff --git a/docs/develop/agents-toolkit-overview.md b/docs/develop/agents-toolkit-overview.md
@@ -1,7 +1,7 @@
 ---
 title: Create Office Add-in projects using Microsoft 365 Agents Toolkit
 description: Learn how to create Office Add-in projects using Microsoft 365 Agents Toolkit.
-ms.date: 05/19/2025
+ms.date: 07/29/2025
 ms.localizationpriority: high
 ---
 
@@ -68,11 +68,18 @@ Install the latest version of Agents Toolkit into Visual Studio Code as describe
     > [!NOTE]
     > Regardless of which button you select, a **WebView Stop On Load** prompt appears. Select **OK**.
 
+    > [!TIP]
+    > Sideloading in Office on Windows also makes the add-in available in Office on the web, so you can test it on that platform too. After this step is complete, minimize the Office on Windows application window and in a browser, navigate to `https://excel.cloud.microsoft/`, `https://word.cloud.microsoft/`, or `https://powerpoint.cloud.microsoft/`, whichever is appropriate for the add-in you're testing. Open a new or existing document in the Office application on the web. The buttons should appear on the **Home** ribbon just as they do in Office on Windows.
+
 1. To stop debugging and uninstall the add-in, select **Run** | **Stop Debugging** in Visual Studio Code.
 
    > [!NOTE]
    > If the preceding step seems to have no effect, uninstall the add-in by opening a **TERMINAL** in Visual Studio Code, and then running 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.
 
+#### Other ways to sideload
+
+See [Sideload Office Add-ins that use the unified manifest for Microsoft 365](../testing/sideload-add-in-with-unified-manifest.md) for alternative ways to sideload an Excel, PowerPoint, or Word add-in, including through the app store in Teams.
+
 ### Sideload in Outlook
 
 > [!NOTE]
diff --git a/docs/includes/unified-manifest-sideload-restrictions-note.md b/docs/includes/unified-manifest-sideload-restrictions-note.md
@@ -1,2 +1,4 @@
 > [!NOTE]
-> Currently, an add-in that uses the [Unified manifest for Microsoft 365](../develop/json-manifest-overview.md) cannot be sideloaded on the web, Mac, or iPad. To sideload an add-in with a unified manifest on Windows, see [Sideload Office Add-ins that uses the unified manifest for Microsoft 365](../testing/sideload-add-in-with-unified-manifest.md).
+> Currently, an add-in that uses the [Unified manifest for Microsoft 365](../develop/json-manifest-overview.md) can't be sideloaded on Mac or iPad. If you work on a Mac, you can test the add-in by having your Microsoft 365 administrator deploy the add-in as an [integrated app](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps) in the Microsoft 365 Admin Center.
+>
+> To sideload an add-in with a unified manifest on Windows and on the web, see [Sideload Office Add-ins that uses the unified manifest for Microsoft 365](../testing/sideload-add-in-with-unified-manifest.md).
diff --git a/docs/testing/sideload-add-in-with-unified-manifest.md b/docs/testing/sideload-add-in-with-unified-manifest.md
@@ -1,16 +1,16 @@
 ---
 title: Sideload Office Add-ins that use the unified manifest for Microsoft 365
 description: Test your Office Add-in on Windows by sideloading.
-ms.date: 05/19/2025
+ms.date: 07/29/2025
 ms.localizationpriority: medium
 ---
 
 # 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](../develop/json-manifest-overview.md) varies depending on the tool you want to use and on how the add-in project was created. 
+The process of sideloading an add-in that uses the [Unified manifest for Microsoft 365](../develop/json-manifest-overview.md) 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.
+> An add-in that uses the unified manifest can be sideloaded on Office on Windows, Version 2304 (Build 16320.20000) or later. Sideloading on Windows has the effect of sideloading to Office on the web too. Currently, it can't be sideloaded on Mac or iPad. If you work on a Mac, you can test the add-in by having your Microsoft 365 administrator deploy the add-in as an [integrated app](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps) in the Microsoft 365 Admin Center.
 
 ## Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)
 
@@ -39,7 +39,7 @@ Use the process described in [Sideload with a system prompt, bash shell, or term
 1. First, *make sure the Office desktop application that you want to sideload into is closed.*
 1. Open a system prompt, bash shell, or the Visual Studio Code **TERMINAL**, and navigate to the root of the project.
 1. 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.
-1. For an Excel, PowerPoint, or Word add-in, there is an additional step: select the **Add-ins** button on the **Home** ribbon. On the flyout that opens, select the add-in. This completes the installation.
+1. 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.
 1. You can now work with your add-in.
 1. 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.
 
@@ -53,21 +53,17 @@ There are two tools you can use to sideload.
 
     ```command&nbsp;line
     npx office-addin-debugging start <relative-path-to-unified-manifest> desktop
-    ``` 
+    ```
 
 1. 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.
 
     ```command&nbsp;line
     npx office-addin-debugging stop <relative-path-to-unified-manifest>
-    ``` 
-
-### Sideload with Microsoft 365 Agents Toolkit CLI (command-line interface) 
+    ```
 
-1. Manually create a zip package using the following steps.
+### Sideload with Microsoft 365 Agents Toolkit CLI (command-line interface)
 
-    1. Open the unified manifest and scroll to the `"icons"` property. Note the relative path of the two image files.
-    1. 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.
-    1. 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).
+1. Create a zip package. See [Manually create the add-in package file](#manually-create-the-add-in-package-file).
 
 1. In the root of the project, open a command prompt or bash shell and run the following command to install the Agents Toolkit CLI.
 
@@ -102,3 +98,83 @@ There are two tools you can use to sideload.
 
     > [!IMPORTANT]
     > The [documentation for the `uninstall` command](/microsoftteams/platform/toolkit/teams-toolkit-cli?pivots=version-three#teamsapp-uninstall) 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](#manually-create-the-add-in-package-file).
+1. Close all Office applications, and then clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+1. Select **Upload an app** in the **Apps** dialog, and then in the dialog that opens, select **Upload a custom app**.
+1. In the **Open** dialog, navigate to, and select, the app package.
+1. Select **Add** in the dialog that opens.
+1. When you're prompted that the app was added, *don't* open it in Teams. Instead, close Teams.
+1. 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](../develop/yeoman-generator-overview.md) or [Microsoft 365 Agent Toolkit](../develop/agents-toolkit-overview.md).
+    - 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.
+
+       ```json
+      "dev-server": "webpack serve --mode development"
+      ```
+
+1. 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.
+1. 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"`](/microsoft-365/extensibility/schema/root-name) property of the manifest.
+
+> [!IMPORTANT]
+> When you want to end a testing session and make changes to the add-in that you sideloaded through the Teams app store, be sure to remove the add-in completely with the following steps. 
+>
+> 1. Close the Office application.
+> 1. Shut down the server. See the documentation for your server application for how to do this. For the webpack dev-server application, shutting it down depends on whether the server is running in the same window in which you ran `npm run dev-server` or a different window. If it's the same window, give the terminal focus and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Choose "Y" in response to the prompt to end the process. If it's in a different window, then in the window where you ran `npm run dev-server`, run `npm run stop`.
+> 1. Clear the Office cache following the instructions at [Manually clear the cache](../testing/clear-cache.md#manually-clear-the-cache).
+> 1. Open Teams and select **Apps** from the app bar, then select **Manage your apps** at the bottom of the **Apps** pane.
+> 1. Find your add-in in the list of apps. It will have the name specified in the `"name.short"` property of the manifest.
+> 1. Select the add-in from the list of apps to expand its row.
+> 1. Select the trash can icon and then select **Remove** in the prompt.
+>
+> Make your changes and then sideload the add-in again.
+
+## 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.
+
+> [!IMPORTANT]
+> *All of these files must have the same relative path in the zip file as specified in the manifest.* For example, if the path of the two image files is **assets/icon-64.png** and **assets/icon-128.png**, then you must include an **assets** folder with the two files in the zip package. Second-level files, such as plugin configuration files for declarative agents, must have the same relative path in the zip file as they do in the first-level file that references them. For example, if the relative path of a declarative agent file specified in the manifest is **agents/myAgent.json**, then you must include an **agents** folder in the zip package and put the **myAgent.json** file in it. If the declarative agent file, in turn, gives the relative path of **plugins/myPlugin.json** for a plugin configuration file, then you must include a **plugins** subfolder under the **agents** folder and put the **myPlugin.json** file in it.
+
+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.
+
+```console
+\appPackage
+    \assets
+        color.png
+        outline.png
+    \build
+        appPackage.zip
+    manifest.json
+```
+
+```console
+\appPackage
+    \agents
+        myAgent.json
+        \plugins
+            myPlugin.json
+    \assets
+        color.png
+        outline.png
+    \build
+        appPackage.zip
+    \languages
+        fr-FR.json
+        es-MX.json
+    manifest.json
+```
diff --git a/docs/testing/sideload-office-add-ins-for-testing.md b/docs/testing/sideload-office-add-ins-for-testing.md
@@ -1,18 +1,18 @@
 ---
 title: Sideload Office Add-ins to Office on the web
 description: Test your Office Add-in in Office on the web by sideloading.
-ms.date: 02/12/2025
+ms.date: 07/29/2025
 ms.localizationpriority: medium
 ---
 
 # Sideload Office Add-ins to Office on the web
 
-> [!NOTE]
-> This article primarily applies to **Excel**, **OneNote**, **PowerPoint**, and **Word** add-ins. For information on sideloading **Outlook** add-ins, see the article [Sideload Outlook add-ins for testing](../outlook/sideload-outlook-add-ins-for-testing.md).
-
 When you sideload an add-in, you're able to install the add-in without first putting it in an add-in catalog. This is useful when testing and developing your add-in because you can see how your add-in will appear and function.
 
-[!INCLUDE [Unified manifest note about platform sideloading restrictions](../includes/unified-manifest-sideload-restrictions-note.md)]
+> [!NOTE]
+>
+> - This article applies to **Excel**, **OneNote**, **PowerPoint**, and **Word** add-ins. For information on sideloading **Outlook** add-ins, see the article [Sideload Outlook add-ins for testing](../outlook/sideload-outlook-add-ins-for-testing.md).
+> - This article applies to add-ins that use the add-in only manifest. For information about sideloading add-ins that use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md), see [Sideload Office Add-ins that use the unified manifest for Microsoft 365](sideload-add-in-with-unified-manifest.md).
 
 When you sideload an add-in on the web, the add-in's manifest is stored in the browser's local storage, so if you clear the browser's cache, or switch to a different browser, you have to sideload the add-in again.
 
