Registry / testing / office-addin-node-debugger

office-addin-node-debugger

library1.0.7jsnpmunverified

The `office-addin-node-debugger` package facilitates web debugging for Office Add-ins by providing a Node.js instance to act as a proxy for the JavaScript runtime hosted by an Office application. It is a foundational component within the `Office-Addin-Scripts` monorepo, a collection of tools and utilities developed by OfficeDev for Office Add-in projects. While primarily intended as an underlying service, its programmatic interfaces can be imported into Node scripts for custom debugging workflows. The package ships with TypeScript types, promoting robust development. The current stable version is 1.0.6, last published about three months ago, suggesting a maintenance-oriented release cadence as part of a larger toolkit. This package differentiates itself by offering a Node.js-based proxy specific to the Office Add-in ecosystem, enabling integration with VS Code for a streamlined debugging experience, particularly against Edge runtimes.

testing

npm install office-addin-node-debugger

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OFFICE-ADDIN-NODE-

office-addin-node-debugger

testingjavascriptv1.0.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startNodeDebugger

✓ import { startNodeDebugger } from 'office-addin-node-debugger';

✗ const startNodeDebugger = require('office-addin-node-debugger').startNodeDebugger;

This is an assumed primary entry point for programmatic debugging. While the `office-addin-debugging` package typically orchestrates, `office-addin-node-debugger` likely exposes lower-level functions for direct control in advanced scenarios. ESM syntax is preferred.

stopNodeDebugger

✓ import { stopNodeDebugger } from 'office-addin-node-debugger';

✗ const stopNodeDebugger = require('office-addin-node-debugger').stopNodeDebugger;

Corresponding function to gracefully terminate the Node.js debugging proxy. Essential for cleanup and resource management after a debugging session.

NodeDebuggerOptions

✓ import type { NodeDebuggerOptions } from 'office-addin-node-debugger';

✗ import { NodeDebuggerOptions } from 'office-addin-node-debugger'; // Importing type as value

Used for type-checking when configuring the debugger programmatically. Should be imported as a type (`import type`) to prevent bundling issues if not used as a value at runtime.

This TypeScript example demonstrates how to programmatically start and stop the Office Add-in Node Debugger proxy. It showcases typical configuration options like manifest path, development server port, and debugger port, providing a basic framework for integrating it into a custom build or test script.

import { startNodeDebugger, stopNodeDebugger } from 'office-addin-node-debugger'; async function setupAndStartDebugging() { // In a real scenario, these would come from environment variables or a configuration file. const manifestPath = process.env.ADDIN_MANIFEST_PATH ?? './manifest.xml'; const devServerPort = parseInt(process.env.DEV_SERVER_PORT ?? '3000'); const debuggerPort = parseInt(process.env.DEBUGGER_PORT ?? '9229'); try { console.log('Starting Office Add-in Node Debugger...'); const debuggerInstance = await startNodeDebugger({ manifestPath, devServerPort, debuggerPort, verbose: true, // The 'app' option would typically specify the Office application (e.g., 'excel', 'word'). // For programmatic use, you might need to infer this or provide it based on context. // app: 'excel', }); console.log(`Node debugger proxy started on port ${debuggerPort}. Waiting for connection...`); // Simulate debugging session for a few seconds await new Promise(resolve => setTimeout(resolve, 15000)); console.log('Stopping Node debugger...'); await stopNodeDebugger(debuggerInstance.pid); // Assuming start returns an object with pid console.log('Node debugger stopped.'); } catch (error: any) { console.error('Failed to start or stop node debugger:', error.message); process.exit(1); } } setupAndStartDebugging();

Debug

Known issues

breakingDebugging capabilities for Office Add-ins have seen systematic changes and restrictions across different Office versions and platforms, particularly on Mac App Store versions and newer Outlook for Windows. This can break existing debugging workflows.

fix

Consult the latest official Microsoft Office Add-ins documentation for specific debugging setup for your Office version, host application, and operating system. Be prepared to use workarounds or alternative debugging methods, such as `olk.exe --devtools` for New Outlook.

affects: >=1.0.0

gotchaOutdated add-in manifests or cached files can lead to debugging issues, where changes in your code or manifest are not reflected in the Office application.

fix

Regularly clear the Office cache, especially after making changes to your add-in manifest or experiencing unexpected behavior. Instructions vary by operating system; typically, this involves specific folders or command-line tools.

affects: >=1.0.0

gotchaUsing older Node.js versions may lead to compatibility issues with `office-addin-node-debugger` and its dependencies.

fix

Ensure you are running a supported Node.js version (e.g., Node.js 10+ is a common prerequisite for related Office Add-in debugging tools). Update Node.js to the latest LTS version if encountering unexpected errors.

affects: <10.0.0

gotchaDebugging tools often require administrative privileges, especially on Windows, for operations like managing certificates or modifying system settings for sideloading and debugging.

fix

Run your command prompt, terminal, or VS Code instance as an administrator when starting debugging sessions or executing Office Add-in related commands to avoid permission-related errors.

affects: >=1.0.0

gotchaPort conflicts are common when running local development servers and debugging proxies simultaneously, leading to 'address already in use' errors.

fix

Configure your development server and debugger to use distinct, available ports. Check for other processes occupying the intended ports using tools like `netstat` (Windows) or `lsof -i :<port>` (Linux/macOS) and terminate them if necessary. Many tools offer options to specify ports (e.g., `--dev-server-port`).

affects: >=1.0.0

Errors

Common errors & fixes

Error: Unable to start debugging.

This generic error often indicates an underlying issue with the debugging environment setup, such as an invalid manifest path, problems with the development server, or Office application not launching correctly.

fix

Verify that your add-in manifest path is correct, your development server is running and accessible, and that the specified Office application can be launched and sideloaded. Check logs for more specific errors.

Port 3000 is already in use.

Another application or process is already listening on the specified port, preventing the debugger's development server or proxy from starting.

fix

Change the port used by your development server or the debugging proxy in your configuration (e.g., `package.json` scripts, `launch.json` in VS Code, or programmatic options). Alternatively, identify and terminate the process currently using the port.

Cannot find module 'office-addin-node-debugger'

The package is not installed or not correctly resolved in your project's `node_modules`. This can happen if `npm install` wasn't run, or if there's an issue with module resolution in a monorepo setup.

fix

Ensure `office-addin-node-debugger` is listed in your `package.json` dependencies and run `npm install` or `yarn install` in your project root. If in a monorepo, verify workspace configurations.

Add-in doesn't load in task pane or ribbon customizations are not rendering.

This is often related to an invalid or uncacheable add-in manifest, browser caching of static files, or issues with the add-in's web server configuration preventing Office from fetching resources.

fix

Validate your add-in's manifest (`npx office-addin-manifest validate <manifest-path>`), clear the Office cache and your browser's cache, and ensure your development server is sending appropriate HTTP headers to prevent caching of static assets.

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

@types/noderequiredTypeScript type definitions for Node.js, essential for development given the package ships with types and runs in a Node environment.

commanderrequiredLikely used for parsing command-line arguments, suggesting it might expose a CLI or sub-commands internally.

https-proxy-agentrequiredCrucial for its core functionality: enabling a Node.js instance to act as an HTTPS proxy for debugging, as stated in its description.

node-fetchrequiredUsed for making HTTP requests in Node.js, possibly for fetching add-in resources or communicating with the Office application.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/OfficeDev/Office-Addin-Scripts ↗

packagehttps://www.npmjs.com/package/office-addin-node-debugger ↗

homepagehttps://learn.microsoft.com/office/dev/add-ins/overview/debug ↗