generator-office

To manually configure your machine to trust the self-signed certificate on Windows, follow these steps:

1. Navigate to the {project root}\certs directory.
2. Double-click ca.crt and select Install Certificate.
3. Select Local Machine and click Next.
4. Select Place all certificates in the following store, click Browse, and select Trusted Root Certification Authorities.
5. Click OK, then click Next, and finally click Finish.

Your self-signed certificate is now installed and trusted.

Office Add-ins require HTTPS to load correctly in Office clients. If you are using a recent version of the Yeoman generator for Office Add-ins, you can install the required self-signed certificate automatically.

When you start your local web server, if a valid certificate is not already present on your machine, you will be prompted by a dialog box to install the certificate. Accept this prompt to add the certificate to your current user's Trusted Root Certification Authorities certificate store.

Once the project is scaffolded, navigate to the project directory and run the following command to launch the local HTTPS site on https://localhost:3000:

npm start

Note: Office Add-ins require HTTPS. If prompted to install a certificate provided by the Yeoman generator, you must accept it to proceed with development. After starting the site, you must sideload the add-in into your Office application to test it.

To ensure your manifest.xml file is correct and complete, you can run the built-in validator using npm. This uses the Office Toolbox to check for errors and provide platform compatibility information.

Run this command from your project directory:

npm run validate

You can run the generator in interactive mode by simply running yo office. Alternatively, you can provide arguments and options to skip prompts.

Important: When using command line arguments, they must be provided in the specific order: --projectType, --name, and then --host. Options (like --js, --ts, or --output) must follow these arguments.

Example of a non-interactive command:

yo office --projectType react --name "New Web AddIn" --host word --ts true

To use this generator, you must first have Node.js (version 8.0.0 or later) installed. Then, install Yeoman globally using npm.

npm install -g yo

If you are using an older version of the generator or the automatic prompt does not appear, follow these steps to trust the certificate on macOS:

1. In Finder, open the certs folder located in the root folder of your project.
2. Double-click the ca.crt file.
3. In the Add Certificates dialog box, click Add.
4. Enter your system credentials and choose Modify Keychain.
5. Open the Keychain Access utility.
6. Select the Certificates category and double-click the localhost-ca certificate.
7. In the Trust section, set When using this certificate to Always Trust.
8. Close the dialog and enter your credentials when prompted to enable the certificate.
9. Quit all browsers and reopen them to navigate to your local HTTPS site.

The Office Add-in CLI tools collect anonymized usage data sent to Microsoft. To disable this data collection, you can run the following command in your terminal:

npx office-addin-usage-data off

Once the generator completes, follow these typical next steps to get your project running:

1. Navigate to the project directory:

   cd <your-project-name>

2. Configure specific features (if applicable):
   • For SSO projects: npm run configure-sso
   • For Excel Custom Functions: npm run build
3. Start the local web server and sideload:
   • For standard hosts (Excel, Word, etc.): npm start
   • For other hosts: npm run dev-server (then follow sideloading instructions for your specific host).
4. Open in VS Code:

   code .

The generator-office (Yo Office) is a Yeoman generator used to scaffold various types of Office Add-in projects, including Task Pane add-ins (React or vanilla), Excel Custom Functions, and Manifest-only projects.

You can run the generator interactively to be prompted for project details, or provide arguments and options directly via the command line to automate the process.

Note: The generator requires a compatible Node.js version (LTS is recommended).

# Interactive mode
yo office

# Non-interactive mode (example)
yo office taskpane my-addin excel --ts

Options should be specified after the arguments. If not specified, the generator will prompt you for them.

The following arguments are supported. They must be used in this specific order to avoid being prompted for values.

Project Types:

• taskpane: Task Pane add-in using HTML
• react: Task Pane add-in using the React framework
• excel-functions: Task Pane add-in with Excel Custom Functions
• nested-app-auth: Taskpane add-in supporting Nested App Auth single sign-on
• manifest: Manifest and related files for an Office Add-in

Supported Hosts:

• excel
• onenote
• outlook
• powerpoint
• project
• word