Create an Office Add-in using any editor
You can use the Yeoman generator to create your Office Add-in. The Yeoman generator provides the project scaffolding and build management. The
manifest.xml file tells the Office application where your add-in is located and how you want it to appear. The Office application takes care of hosting it within Office.
Note: These instructions use Terminal on a Mac, but you can also use other shell environments.
Prerequisites for the Yeoman generator
To install the Yeoman Office generator, you must have git and node.js installed on your computer. If you're on a Mac, we recommend that you use Node Version Manager to install node.js with the right permissions. If you're on Windows, you can install node.js from nodejs.org.
Note: If you're on Windows, use the default values when you install git, with the following exceptions:
- Use git from the Windows command prompt
- Use the Windows default console window
After you install node.js, open a Terminal and install the generator globally.
npm install -g yo generator-office
Create the default files for your add-in
The Yeoman generator runs in the directory where you want to scaffold the project. Before you develop an Office Add-in, you should first create a folder for your project.
In Terminal, move to the parent folder where you want to create your project. Then use the following commands create a new folder named myHelloWorldaddin and shift the current directory to it:
mkdir myHelloWorldaddin cd myHelloWorldaddin
Use the Yeoman generator to create the add-in of your choice. The steps in this article create a simple task pane add-in. To run the generator, enter the following command:
Yeoman generator input for an add-in
The generator will prompt you for the following:
- New subfolder -- use N
- Add-in name -- use myHelloWorldaddin
- The supported Office application - you can choose any application
- Create new add-in -- use Yes, I want a new add-in.
- Add TypeScript -- use N
- Choose framework -- use Jquery
Note: If you want to create an Office Add-in that uses Office UI Fabric React, enter the following: - Add TypeScript -- use Y - Choose framework -- use React
This creates the structure and basic files for your add-in.
Hosting your Office Add-in
Office Add-ins must be hosted, even in development, via HTTPS. Yo Office creates a bsconfig.json, which uses Browsersync to make it faster for you to tweak and test your add-in by synchronizing file changes across multiple devices.
Launch the local HTTPS site on https://localhost:3000 by typing the following command in your console:
Browsersync will start a HTTPS server, and launch the index.html file in your project. You will see an error that states "There is a problem with this website's security certificate."
This error occurs because Browsersync includes a self-signed SSL certificate that your development environment must trust. For information about how to resolve this error, see adding self-signed certificates.
Sideload the add-in into Office
You can use sideloading to install your add-in for testing within the Office clients:
- Sideload Office Add-ins for testing
- Sideload Office Add-ins on iPad and Mac for testing
- Sideload Outlook add-ins for testing
Develop your Office Add-in
You can use any text editor to develop the files for your custom Office Add-in.
Important: The manifest-myHelloWorldaddin.xml file tells the Office client applications how to interact with your add-in. The value in the
<id>tag is a GUID that Yo Office creates when it generates the project. Do not change the GUID for your add-in. If the host is Azure, the
SourceLocationvalue will be a URL that is similar to https:// [name-of-your-web-app].azurewebsites.net/[path-to-add-in]. If you are using the self-hosted option, as in this example, it will be https://localhost:3000/[path-to-add-in].
Debug your Office Add-in
You can debug your add-in in several ways:
- Attach a debugger from the task pane (Office 2016 for Windows).
- Use your browser's developer tools.
- Use F12 developer tools in Windows 10.
Attach debugger from the task pane
In Office 2016 for Windows, Build 77xx.xxxx or later, you can attach the debugger from the task pane.
To launch the Attach Debugger tool, choose the top right corner of the task pane to activate the Personality menu (as shown in the red circle in the following image).
Select Attach Debugger. This launches the Visual Studio Just-in-Time Debugger dialog box, as shown in the following image.
You can then attach and debug in Visual Studio.
For more information, see the following:
- To launch and use the DOM Explorer in Visual Studio, see Tip 4 in the Tips and Tricks section of the Building great-looking apps for Office using the new project templates blog post.
- To set breakpoints, see Using Breakpoints.
- To use F12, see Using the F12 developer tools.
Browser developer tools
F12 developer tools on Windows 10
If you're using the Office desktop client on Windows 10, you can Debug add-ins using F12 developer tools on Windows 10.