Create Synchronous Custom Functions in Excel (preview)

10/20/2026

A workbook with a synchronous custom function reading cell values.

This sample shows how to create a synchronous custom function that reads a cell value in tandem with Excel calculation processes. You'll learn how to:

Create synchronous custom functions in Excel
Use the shared runtime

Note: Synchronous custom functions are currently in public preview and require the preview version of the Office JavaScript API. Do not use this feature in a production add-in.

How to run this sample

Prerequisites

Node.js (the latest LTS version). Visit the Node.js site to download and install the right version for your operating system. To verify if you've already installed these tools, run the commands node -v and npm -v in your terminal.
Microsoft Office connected to a Microsoft 365 subscription. You might qualify for a Microsoft 365 E5 developer subscription through the Microsoft 365 Developer Program, see FAQ for details. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

Run the add-in

Open a Command Prompt, Terminal, or bash shell.
Run npm install.
When the installation is finished, run npm start. A web server launches and Excel opens. This may take several minutes.
See Use the sample add-in for instructions about running the add-in.

Note: It is important to uninstall the add-in completely after working with it. To do so, run npm stop in the same window that you ran npm start. Close Excel. We recommend that you clear the office cache.

Use the sample add-in

If the Sync CF Sample control group doesn't automatically appear on the Excel Home tab ribbon, select the Add-ins button on the Home tab. Select the add-in on the flyout that opens.
Select the Set up sample data button in the task pane to populate the active worksheet with sample values.
Cells B2 and B3 use the GETCELLVALUE synchronous custom function to read values from A2 and A3.
Change the values in A2 or A3 to see the synchronous custom function update automatically during Excel's calculation.

The add-in adds the following custom function to the workbook.

=SyncCFSample.GETCELLVALUE("A1"): Reads the value of the specified cell, evaluated synchronously with Excel's calculation.

Note: It is important to uninstall the add-in completely after working with it. To do so, run npm stop in the same window that you ran npm start. Close Excel. We recommend that you clear the office cache.

Explore sample files

These are the important files in the sample project.

| .eslintrc.json
| .gitignore
| .vscode/
|   | extensions.json
|   | launch.json               Launch and debug configurations
|   | settings.json
|   | tasks.json
| assets/                       Static assets, such as images
| babel.config.json
| manifest*.xml                 Manifest file
| package.json
| README.md
| src/                          Add-ins source code
|   | taskpane/
|   |   | taskpane.html         Task pane entry HTML
|   |   | taskpane.js           Add API calls and logic here
|   | functions/
|   |   | functions.ts          Custom function TypeScript
| tsconfig.json
| webpack.config.js             Webpack config

Details

Create the synchronous custom function

The getCellValue function in functions.ts is marked with @supportSync so that it evaluates during Excel's calculation cycle. It creates a new Excel.RequestContext, calls setInvocation with the invocation parameter, and reads a cell value. For more details see the getCellValue function in functions.ts.

Set up and use the custom function

The taskpane.js file populates sample data in column A and inserts formulas using GETCELLVALUE in column B. When you change a value in column A, the synchronous custom function re-evaluates during the Excel calculation and column B updates automatically.

Troubleshooting

If you have problems running the sample, take the following steps.

Close any open instances of Excel.
Open a Command Prompt, Terminal, or bash shell in the project sample and run npm stop.
Try to run the sample again.

If you still have problems, see troubleshoot development errors or create a GitHub issue and we'll help you.

For information on running the sample on Excel on the web, see Sideload Office Add-ins to Office on the web.

For information on debugging on older versions of Office, see Debug add-ins using developer tools in Microsoft Edge Legacy.

Make code changes

Once you understand the sample, make it your own! All the information about Office Add-ins is found in our official documentation.

Engage with the team

Did you experience any problems with the sample? Create an issue and we'll help you out.

Copyright

Copyright (c) 2026 Microsoft Corporation. All rights reserved. This project has 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.