Office Add-in Node Debugger

Common errors

• Error: Unable to start debugging.

  cause 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.

  cause 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'

  cause 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.

  cause 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.

Warnings

• breaking Debugging 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.
• gotcha Outdated 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.
• gotcha Using 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.
• gotcha Debugging 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.
• gotcha Port 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`).

Install

• npm install office-addin-node-debugger npm
• yarn add office-addin-node-debugger yarn
• pnpm add office-addin-node-debugger pnpm

Imports

• startNodeDebugger
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

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

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

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

  correct:

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

  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.

Quickstart

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();