Referencing the Office JavaScript API library

The Office JavaScript API library provides the APIs that your add-in can use to interact with the Office host. The simplest way to reference the library is to use the content delivery network (CDN) by adding the following <script> tag within the <head> section of your HTML page:

<head>
    ...
    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
</head>

This will download and cache the Office JavaScript API files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Important

You must reference the Office JavaScript API from inside the <head> section of the page to ensure that the API is fully initialized prior to any body elements. Office hosts require that add-ins initialize within 5 seconds of activation. If your add-in doesn't activate within this threshold, it will be declared unresponsive and an error message will be displayed to the user.

API versioning and backward compatibility

In the previous HTML snippet, the /1/ in front of office.js in the CDN URL specifies the latest incremental release within version 1 of Office.js. Because the Office JavaScript API maintains backward compatibility, the latest release will continue to support API members that were introduced earlier in version 1. If you need to upgrade an existing project, see Update the version of your Office JavaScript API and manifest schema files.

If you plan to publish your Office Add-in from AppSource, you must use this CDN reference. Local references are only appropriate for internal, development, and debugging scenarios.

Note

To use preview APIs, reference the preview version of the Office JavaScript API library on the CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

Enabling Intellisense for a TypeScript project

In addition to referencing the Office JavaScript API as described previously, you can also enable Intellisense for TypeScript add-in project by using the type definitions from DefinitelyTyped. To do so, run the following command in a Node-enabled system prompt (or git bash window) from the root of your project folder. You must have Node.js installed (which includes npm).

npm install --save-dev @types/office-js

Note

To enable Intellisense for preview APIs, use the preview type definitions from DefinitelyTyped by running the following command in the root of your project folder:

npm install --save-dev @types/office-js-preview

See also