Configure your Office Add-in to use a shared JavaScript runtime

Important

The shared JavaScript runtime is only supported in some Office applications. For more information, see Shared runtime requirement sets.

You can configure your Office Add-in to run all of its code in a single shared JavaScript runtime (also known as a shared runtime). This enables better coordination across your add-in and access to the DOM and CORS from all parts of your add-in. It also enables additional features such as running code when the document opens, or enabling or disabling ribbon buttons. To configure your add-in to use a shared JavaScript runtime, follow the instructions in this article.

Create the add-in project

If you are starting a new project, follow these steps to use the Yeoman generator for Office Add-ins to create an Excel or PowerPoint add-in project.

Do one of the following:

  • To generate an Excel add-in with custom functions, run the command yo office --projectType excel-functions --name 'Excel shared runtime add-in' --host excel --js true.

    or

  • To generate a PowerPoint add-in, run the command yo office --projectType taskpane --name 'PowerPoint shared runtime add-in' --host powerpoint --js true.

The generator will create the project and install supporting Node components.

Note

You can also use the steps in this article to update an existing Visual Studio project to use the shared runtime. However, you may need to update the XML schemas for the manifest. For more information, see Troubleshoot development errors with Office Add-ins.

Configure the manifest

Follow these steps for a new or existing project to configure it to use a shared runtime. These steps assume you have generated your project using the Yeoman generator for Office Add-ins.

  1. Start Visual Studio Code and open the Excel or PowerPoint add-in project you generated.

  2. Open the manifest.xml file.

  3. If you generated an Excel add-in, update the requirements section to use the shared runtime instead of the custom function runtime. The XML should appear as follows.

    <Hosts>
      <Host Name="Workbook"/>
    </Hosts>
    <Requirements>
      <Sets DefaultMinVersion="1.1">
        <Set Name="SharedRuntime" MinVersion="1.1"/>
      </Sets>
    </Requirements>
    <DefaultSettings>
    
  4. Find the <VersionOverrides> section and add the following <Runtimes> section. The lifetime needs to be long so that your add-in code can run even when the task pane is closed. The resid value is Taskpane.Url, which references the taskpane.html file location specified in the <bt:Urls> section near the bottom of the manifest.xml file.

    Important

    The <Runtimes> section must be entered after the <Host> element in the exact order shown in the following XML.

    <VersionOverrides ...>
      <Hosts>
        <Host ...>
          <Runtimes>
            <Runtime resid="Taskpane.Url" lifetime="long" />
          </Runtimes>
        ...
        </Host>
    
  5. If you generated an Excel add-in with custom functions, find the <Page> element. Then change the source location from Functions.Page.Url to Taskpane.Url.

    <AllFormFactors>
    ...
    <Page>
      <SourceLocation resid="Taskpane.Url"/>
    </Page>
    ...
    
  6. Find the <FunctionFile ...> tag and change the resid from Commands.Url to Taskpane.Url. Note that if you don't have action commands, you won't have a FunctionFile entry, and can skip this step.

    </GetStarted>
    ...
    <FunctionFile resid="Taskpane.Url"/>
    ...
    
  7. Save the manifest.xml file.

Configure the webpack.config.js file

The webpack.config.js will build multiple runtime loaders. You need to modify it to load only the shared JavaScript runtime via the taskpane.html file.

  1. Start Visual Studio Code and open the Excel or PowerPoint add-in project you generated.

  2. Open the webpack.config.js file.

  3. If your webpack.config.js file has the following functions.html plugin code, remove it.

    new HtmlWebpackPlugin({
        filename: "functions.html",
        template: "./src/functions/functions.html",
        chunks: ["polyfill", "functions"]
      })
    
  4. If your webpack.config.js file has the following commands.html plugin code, remove it.

    new HtmlWebpackPlugin({
        filename: "commands.html",
        template: "./src/commands/commands.html",
        chunks: ["polyfill", "commands"]
      })
    
  5. If your project used either the functions or commands chunks, add them to the chunks list as shown next (the following code is for if your project used both chunks).

      new HtmlWebpackPlugin({
        filename: "taskpane.html",
        template: "./src/taskpane/taskpane.html",
        chunks: ["polyfill", "taskpane", "commands", "functions"]
      })
    
  6. Save your changes and rebuild the project.

    npm run build
    

Note

If your project has a functions.html file or commands.html file, they can be removed. The taskpane.html will load the functions.js and commands.js code into the shared JavaScript runtime via the webpack updates you just made.

Test your Office Add-in changes

You can confirm that you are using the shared JavaScript runtime correctly by using the following instructions.

  1. Open the manifest.xml file.

  2. Find the <Control xsi:type="Button" id="TaskpaneButton"> section and change the following <Action ...> XML.

    from:

    <Action xsi:type="ShowTaskpane">
      <TaskpaneId>ButtonId1</TaskpaneId>
      <SourceLocation resid="Taskpane.Url"/>
    </Action>
    

    to:

    <Action xsi:type="ExecuteFunction">
      <FunctionName>action</FunctionName>
    </Action>
    
  3. Open the ./src/commands/commands.js file.

  4. Replace the action function with the code below. This will update the function to open and modify the task pane button to increment a counter. Opening and accessing the task pane DOM from a command only works with the shared JavaScript runtime.

    var _count=0;
    
    function action(event) {
      // Your code goes here.
      _count++;
      Office.addin.showAsTaskpane();
      document.getElementById("run").textContent="Go"+_count;
    
      // Be sure to indicate when the add-in command function is complete.
      event.completed();
    }
    
  5. Save your changes and run the project.

    npm start
    

Each time you select the add-ins button, it will change the run button text to go and increment a counter after it.

Runtime lifetime

When you add the Runtime element, you also specify a lifetime with a value of long or short. Set this value to long to take advantage of features such as starting your add-in when the document opens, continuing to run code after the task pane is closed, or using CORS and DOM from custom functions.

Note

The default lifetime value is short, but we recommend using long in Excel add-ins. If you set your runtime to short in this example, your Excel add-in will start when one of your ribbon buttons is pressed, but it may shut down after your ribbon handler is done running. Similarly, your add-in will start when the task pane is opened, but it may shut down when the task pane is closed.

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

Note

If your add-in includes the Runtimes element in the manifest (required for a shared runtime) and the conditions for using Microsoft Edge with WebView2 (Chromium-based) are met, it uses that WebView2 control. If the conditions are not met, then it uses Internet Explorer 11 regardless of the Windows or Microsoft 365 version. For more information, see Runtimes and Browsers used by Office Add-ins.

About the shared JavaScript runtime

On Windows or Mac, your add-in will run code for ribbon buttons, custom functions, and the task pane in separate JavaScript runtime environments. This creates limitations such as not being able to easily share global data, and not being able to access all CORS functionality from a custom function.

However, you can configure your Office Add-in to share code in the same JavaScript runtime (also referred to as a shared runtime). This enables better coordination across your add-in and access to the task pane DOM and CORS from all parts of your add-in.

Configuring a shared runtime enables the following scenarios.

For Office on Windows, the shared runtime uses Microsoft Edge with WebView2 (Chromium-based) if the conditions for using it are met as explained in Browsers used by Office Add-ins. Otherwise, it uses Internet Explorer 11. Additionally, any buttons that your add-in displays on the ribbon will run in the same shared runtime. The following image shows how custom functions, the ribbon UI, and the task pane code will all run in the same JavaScript runtime.

Diagram of a custom function, task pane, and ribbon buttons all running in a shared browser runtime in Excel.

Debugging

When using a shared runtime, you can't use Visual Studio Code to debug custom functions in Excel on Windows at this time. You'll need to use developer tools instead. For more information, see Debug add-ins using developer tools on Windows.

Multiple task panes

Don't design your add-in to use multiple task panes if you are planning to use a shared runtime. A shared runtime only supports the use of one task pane. Note that any task pane without a <TaskpaneID> is considered a different task pane.

Give us feedback

We'd love to hear your feedback on this feature. If you find any bugs, issues, or have requests on this feature, please let us know by creating a GitHub issue in the office-js repo.

See also