{"id":14782,"library":"office-addin-node-debugger","title":"Office Add-in Node Debugger","description":"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.","status":"active","version":"1.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/OfficeDev/Office-Addin-Scripts","tags":["javascript","Office","Node Debugger","typescript"],"install":[{"cmd":"npm install office-addin-node-debugger","lang":"bash","label":"npm"},{"cmd":"yarn add office-addin-node-debugger","lang":"bash","label":"yarn"},{"cmd":"pnpm add office-addin-node-debugger","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"TypeScript type definitions for Node.js, essential for development given the package ships with types and runs in a Node environment.","package":"@types/node","optional":false},{"reason":"Likely used for parsing command-line arguments, suggesting it might expose a CLI or sub-commands internally.","package":"commander","optional":false},{"reason":"Crucial for its core functionality: enabling a Node.js instance to act as an HTTPS proxy for debugging, as stated in its description.","package":"https-proxy-agent","optional":false},{"reason":"Used for making HTTP requests in Node.js, possibly for fetching add-in resources or communicating with the Office application.","package":"node-fetch","optional":false}],"imports":[{"note":"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.","wrong":"const startNodeDebugger = require('office-addin-node-debugger').startNodeDebugger;","symbol":"startNodeDebugger","correct":"import { startNodeDebugger } from 'office-addin-node-debugger';"},{"note":"Corresponding function to gracefully terminate the Node.js debugging proxy. Essential for cleanup and resource management after a debugging session.","wrong":"const stopNodeDebugger = require('office-addin-node-debugger').stopNodeDebugger;","symbol":"stopNodeDebugger","correct":"import { stopNodeDebugger } from 'office-addin-node-debugger';"},{"note":"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.","wrong":"import { NodeDebuggerOptions } from 'office-addin-node-debugger'; // Importing type as value","symbol":"NodeDebuggerOptions","correct":"import type { NodeDebuggerOptions } from 'office-addin-node-debugger';"}],"quickstart":{"code":"import { startNodeDebugger, stopNodeDebugger } from 'office-addin-node-debugger';\n\nasync function setupAndStartDebugging() {\n  // In a real scenario, these would come from environment variables or a configuration file.\n  const manifestPath = process.env.ADDIN_MANIFEST_PATH ?? './manifest.xml';\n  const devServerPort = parseInt(process.env.DEV_SERVER_PORT ?? '3000');\n  const debuggerPort = parseInt(process.env.DEBUGGER_PORT ?? '9229');\n\n  try {\n    console.log('Starting Office Add-in Node Debugger...');\n    const debuggerInstance = await startNodeDebugger({\n      manifestPath,\n      devServerPort,\n      debuggerPort,\n      verbose: true,\n      // The 'app' option would typically specify the Office application (e.g., 'excel', 'word').\n      // For programmatic use, you might need to infer this or provide it based on context.\n      // app: 'excel',\n    });\n    console.log(`Node debugger proxy started on port ${debuggerPort}. Waiting for connection...`);\n\n    // Simulate debugging session for a few seconds\n    await new Promise(resolve => setTimeout(resolve, 15000));\n\n    console.log('Stopping Node debugger...');\n    await stopNodeDebugger(debuggerInstance.pid); // Assuming start returns an object with pid\n    console.log('Node debugger stopped.');\n  } catch (error: any) {\n    console.error('Failed to start or stop node debugger:', error.message);\n    process.exit(1);\n  }\n}\n\nsetupAndStartDebugging();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Using older Node.js versions may lead to compatibility issues with `office-addin-node-debugger` and its dependencies.","severity":"gotcha","affected_versions":"<10.0.0"},{"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.","message":"Debugging tools often require administrative privileges, especially on Windows, for operations like managing certificates or modifying system settings for sideloading and debugging.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"Port conflicts are common when running local development servers and debugging proxies simultaneously, leading to 'address already in use' errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Unable to start debugging."},{"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.","cause":"Another application or process is already listening on the specified port, preventing the debugger's development server or proxy from starting.","error":"Port 3000 is already in use."},{"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.","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.","error":"Cannot find module 'office-addin-node-debugger'"},{"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.","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.","error":"Add-in doesn't load in task pane or ribbon customizations are not rendering."}],"ecosystem":"npm"}