first-run-experience-tutorial

page_type	sample
urlFragment	office-add-in-first-run-experience-tutorial
products	m365 office office-excel office-onenote office-outlook office-powerpoint office-project office-word
languages	javascript
extensions	contentType technologies createdDate samples Add-ins 09/05/2024 4:00:00 PM
description	A completed version of the step-by-step first-run experience tutorial hosted on learn.microsoft.com.

Office Add-in First-run Experience Tutorial - Completed

Summary

This sample is the result of completing the Build an Office Add-in with a basic first-run experience tutorial. It's built from the Yeoman generator for Office Add-ins.

The tutorial gives step-by-step instructions on how to add functionality alongside explanations as to why code is being added. Use this sample if you want to explore and try the completed code, or if you need to debug any issues you encountered while following the tutorial.

Features

This sample demonstrates the basics of implementing a first-run experience (FRE) in Excel. The pattern can be applied to other Office applications where Office Web Add-ins are supported.

Applies to

• Excel on Windows
• Excel on Mac
• Excel on the web

The first-run experience pattern demonstrated in this sample can also be applied to the following Office applications. However, you won't be able to run this sample directly in these applications. See the step-by-step tutorial for details.

• OneNote on the web
• Outlook
• PowerPoint
• Project on Windows
• Word

Prerequisites

• Office connected to a Microsoft 365 subscription (including Office on the web).
• Node.js (latest recommended version).
• npm version 8 or greater.

Solution

Solution	Authors
Learn the basics of implementing a first-run experience	Microsoft

Version history

Version	Date	Comments
1.0	9-5-2024	Initial release
1.1	2-11-2026	Added support for the unified manifest for Microsoft 365

Choose a manifest type

By default, the sample uses an add-in only manifest. However, you can switch the project between the add-in only manifest and the unified manifest for Microsoft 365. For more information about the differences between them, see Office Add-ins manifest. To continue with the add-in only manifest, skip ahead to the Run the sample section.

Note

To run the sample in Outlook on Mac, use the add-in only manifest. For more information on manifests and their supported platforms, see Office Add-in manifest.

To switch to the unified manifest for Microsoft 365

Copy all the files from the manifest-configurations/unified subfolder to the sample's root folder, replacing any existing files that have the same names. We recommend that you delete the manifest.xml file from the root folder, so only files needed for the unified manifest are present. Then, run the sample.

To switch back to the add-in only manifest

To switch back to the add-in only manifest, copy the files from the manifest-configurations/add-in-only subfolder to the sample's root folder. We recommend that you delete the manifest.json file from the root folder.

Run the sample

1. Fork and download this repo.

2. Go to the Samples/tutorials/first-run-experience-tutorial/My Office Add-in folder via the command line.

3. Run npm install.

4. Run npm run build.

5. Start the local web server and sideload your add-in.

   • To test your add-in in Excel, run the following command in the root directory of your project. This starts the local web server (if it's not already running) and opens Excel with your add-in loaded.

     • Windows: npm start
     • Mac: npm run dev-server

   • To test your add-in in Excel on the web, run the following command in the root directory of the My Office Add-in project. When you run this command, the local web server starts. Replace "{url}" with the URL of an Excel document on your OneDrive or a SharePoint library to which you have permissions.

     npm run start:web -- --document {url}

     The following are examples.

     • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     NOTE: If you are developing on a Mac, enclose the {url} in single quotation marks. Do not do this on Windows.

     If your add-in doesn't sideload in the document, manually sideload it by following the instructions in Manually sideload add-ins to Office on the web.

6. If the add-in task pane isn't already open in Excel, go to the Home tab and choose the Show Task Pane button in the ribbon to open it.

7. Verify that the list of Office Add-ins features is displayed. This indicates that the first-run experience was shown.

8. Close the task pane then reopen it. Verify that the task pane no longer displays the list of of features.

9. When you want to stop the local web server and uninstall the add-in, follow the applicable instructions:

   • To stop the server, run npm stop. This also uninstalls the add-in if it was automatically sideloaded.
   • If you manually sideloaded the add-in, see Remove a sideloaded add-in.

See also

The version of this sample that you create step-by-step is found in the Build an Office Add-in with a basic first-run experience tutorial.

Copyright

Copyright (c) Microsoft Corporation. All rights reserved.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.