excel-shared-runtime-global-state

page_type	sample
urlFragment	office-add-in-shared-runtime-global-data
products	m365 office office-excel
languages	javascript
extensions	contentType technologies createdDate samples Add-ins 3/15/2020 1:25:00 PM
description	This sample shows how to share data between the task pane and custom functions by using a shared runtime.

Share global data across add-in components

Summary

This sample shows how to set up a basic project that uses the shared runtime. The shared runtime runs add-in components in a single browser runtime, which enables shared data behavior between the task pane and custom functions through local storage or global variables.

Features

• Share data globally between the task pane and custom functions.
• Demonstrates shared runtime with custom functions.
• Offers either unified manifest for Microsoft 365 or XML manifest options.

Applies to

• Excel on Windows, Mac, and the web.

Prerequisites

• Microsoft 365.
• Office 2304 (Build 16320.20000) or later for unified manifest support.

Solution

Solution	Author(s)
Office Add-in share global data with a shared runtime	Microsoft

Version history

Version	Date	Comments
1.0	March 15, 2020	Initial release.
1.1	May 26, 2021	Update to use GitHub pages for hosting.
1.2	May 12, 2026	Add unified manifest support.

---

Scenario: Sharing key/value pairs

This sample enables a user to store and retrieve key/value pairs by using the task pane or custom functions. The user can select which type of storage to use. They can choose to store key/value pairs in local storage, or choose to use a global variable.

Key parts of this sample

Unified or XML manifest options

There are two types of manifests for Office Add-ins. For more information about the differences between them, see Office Add-ins manifest.

To use the unified manifest for Microsoft 365, follow the steps in Run the sample with the unified manifest. To use the XML manifest, follow the steps in Run the sample with the XML manifest in Excel on the web or Run the sample with the XML manifest from localhost.

Global variable

The task pane and custom functions share data through a common state module in the shared runtime. You can switch the method of storage by choosing either the Global variable or Local storage radio buttons on the task pane.

Global state

Global state is initialized in src/shared/state.js and stored on globalThis.g.state. This state is imported and used by both src/taskpane/taskpane.js and src/functions/functions.js, so both surfaces access the same runtime state bag.

How to use this sample

Once the add-in is loaded use the following steps to try out the functionality.

1. On the Home tab, select Show TaskPane.
2. In the task pane, enter a key/value pair, and select Store key/value pair.
3. In any spreadsheet cell, enter the formula =CONTOSO.GETVALUEFORKEYCF("1"). Pass the value of the key you created from the task pane.
4. In any spreadsheet cell, enter the formula =CONTOSO.SETVALUEFORKEYCF("2","oranges"). The formula returns the text Stored key/value pair.
5. In the task pane, enter the key from the previous formula 2 and select Get value for key. The task pane displays the value oranges.

Run the sample with the unified manifest

This sample includes a manifest.json file that uses the unified manifest format for Microsoft 365.

Important: Custom functions are only available in preview with the unified manifest. Don't use custom functions with the unified manifest in a production add-in.

Note: The unified manifest requires Office 2304 (Build 16320.20000) or later.

Use the unified manifest

The unified manifest configures the shared runtime and custom functions in a single runtime object:

{
  "runtimes": [
    {
      "id": "SharedRuntime",
      "type": "general",
      "lifetime": "long",
      "code": {
        "page": "https://localhost:3000/src/taskpane/taskpane.html",
        "script": "https://localhost:3000/functions.js"
      },
      "actions": [...],
      "customFunctions": {
        "namespace": {
          "id": "CONTOSO",
          "name": "CONTOSO"
        },
        "metadataUrl": "https://localhost:3000/functions.json"
      }
    }
  ]
}

The functions.json metadata file is authored in src/functions/functions.json and copied to /functions.json at build time.

In current unified-manifest preview behavior, custom functions might not be available until the shared runtime page loads. If formulas return #NAME?, select Show Taskpane once and then retry.

Build and run with the unified manifest

1. Install dependencies.

   npm install

2. Start the development server.

   npm start

3. The add-in loads in Excel with the unified manifest.

For production builds with GitHub Pages URLs:

npm run build
npm run start:prod

Run the sample with the XML manifest in Excel on the web

You can run this sample in Excel on the web. The add-in web files are served from this repo on GitHub.

1. Download the manifest.xml file from this sample to a folder on your computer.
2. Open Excel on the web.
3. Open a new blank workbook.
4. On the Home tab on the ribbon in the Add-ins section, select Add-ins and then Advanced....
5. On the Office Add-ins dialog, select Upload My Add-in.
6. Browse to the add-in manifest file, and then select Upload.
7. Verify that the add-in loaded successfully. You will see a Show Taskpane button on the Home tab on the ribbon.

The XML manifest is configured to use the shared runtime by using the Runtimes element as follows:

<Runtimes>
   <Runtime resid="Shared.Url" lifetime="long" />
</Runtimes>

In other parts of the XML manifest, you'll see that the custom functions and task pane are also configured to use the Shared.Url because they all run in the same runtime. Shared.Url points to taskpane.html which loads the shared runtime.

Run the sample with the XML manifest from localhost

If you prefer to host the web server for the sample on your computer, follow these steps:

1. You need http-server to run the local web server. If you didn't install this tool yet, install it by running the following command:

   npm install --global http-server

2. Use a tool such as OpenSSL to generate a self-signed certificate that you can use for the web server. Move the cert.pem and key.pem files to the root folder for this sample.

3. From a command prompt, go to the root folder and run the following command:

   http-server -S --cors . -p 3000

4. To reroute to localhost, run office-addin-https-reverse-proxy. If you didn't install this tool yet, install it by running the following command:

   npm install --global office-addin-https-reverse-proxy

   To reroute, run the following command in another command prompt:

   office-addin-https-reverse-proxy --url http://localhost:3000

5. Follow the steps in Run the sample with the XML manifest in Excel on the web, but upload the manifest-localhost.xml file for step 6.

Questions and feedback

• Did you experience any problems with the sample? Create an issue and we'll help you out.
• We'd love to get your feedback about this sample. Go to our Office samples survey to give feedback and suggest improvements.
• For general questions about developing Office Add-ins, go to Microsoft Q&A using the office-js-dev tag.

Copyright

Copyright (c) 2020 Microsoft Corporation. All rights reserved.

This project 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.