Edit

JavaScript-only runtime for custom functions

  • Article

Custom functions that don't use a shared runtime use a JavaScript-only runtime that is designed to optimize performance of calculations.

Important

Note that Excel custom functions are available on the following platforms.

  • Office on Windows
    • Microsoft 365 subscription
    • retail perpetual Office 2016 and later
  • Office on Mac
  • Office on the web

Excel custom functions are currently not supported in the following:

  • Office on iPad
  • volume-licensed perpetual versions of Office 2019 or earlier

Note

We recommend using custom functions with a shared runtime, unless you have a specific reason not to use a shared runtime. Note that using a shared runtime means your add-in will use WebView2 (Microsoft Edge Chromium-based) if conditions are met, and otherwise your add-in will use Trident (Internet Explorer 11) regardless of the Windows or Microsoft 365 version. For a description of the WebView2 conditions, see Browsers and webview controls used by Office Add-ins. For more information about runtimes, see Runtimes in Office Add-ins and Runtimes.

This JavaScript-only runtime provides access to APIs in the OfficeRuntime namespace that can be used by custom functions and the task pane (which runs in a different runtime) to store data.

Request external data

Within a custom function, you can request external data by using an API like Fetch or by using XmlHttpRequest (XHR), a standard web API that issues HTTP requests to interact with servers.

Be aware that custom functions must use additional security measures when making XmlHttpRequests, requiring Same Origin Policy and simple CORS.

A simple CORS implementation cannot use cookies and only supports simple methods (GET, HEAD, POST). Simple CORS accepts simple headers with field names Accept, Accept-Language, Content-Language. You can also use a Content-Type header in simple CORS, provided that the content type is application/x-www-form-urlencoded, text/plain, or multipart/form-data.

Store and access data

Within a custom function that doesn't use a shared runtime, you can store and access data by using the OfficeRuntime.storage object. The Storage object is a persistent, unencrypted, key-value storage system that provides an alternative to localStorage, which cannot be used by custom functions that use the JavaScript-only runtime. The Storage object offers 10 MB of data per domain. Domains can be shared by more than one add-in.

The Storage object is a shared storage solution, meaning multiple parts of an add-in are able to access the same data. For example, tokens for user authentication may be stored in the Storage object because it can be accessed by both a custom function (using the JavaScript-only runtime) and a task pane (using a full webview runtime). Similarly, if two add-ins share the same domain (for example, www.contoso.com/addin1, www.contoso.com/addin2), they are also permitted to share information back and forth through the Storage object. Note that add-ins which have different subdomains will have different instances of Storage (for example, subdomain.contoso.com/addin1, differentsubdomain.contoso.com/addin2).

Because the Storage object can be a shared location, it is important to realize that it is possible to override key-value pairs.

The following methods are available on the Storage object.

  • getItem
  • getItems
  • setItem
  • setItems
  • removeItem
  • removeItems
  • getKeys

Note

There's no method for clearing all information (such as clear). Instead, you should instead use removeItems to remove multiple entries at a time.

OfficeRuntime.storage example

The following code sample calls the OfficeRuntime.storage.setItem method to set a key and value into storage.

function StoreValue(key, value) {

  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

Next steps

Learn how to debug custom functions.

See also