Debugging Your Tool

Power Platform ToolBox supports a full end-to-end debugging workflow using development builds with source maps and the built-in debug loader. This guide walks you through every step from configuring your build to setting breakpoints in DevTools.

Overview

The debugging workflow consists of three main parts:

1. Build – compile your tool in development mode so that source maps are emitted alongside the output
2. Load – use the PPTB debug loader to mount your local tool directory inside the app
3. Inspect – open DevTools on the tool's webview and use breakpoints, the console, and the network panel to investigate issues

Step 1: Enable Source Maps

Source maps allow DevTools to display your original TypeScript (or un-bundled JavaScript) source files instead of the compiled output, making it possible to set meaningful breakpoints and read readable stack traces.

Vite projects (generated by yo pptb)

The generator adds a development mode configuration to vite.config.ts that enables source maps automatically:

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => ({
  build: {
    sourcemap: mode === 'development', // emitted only in development builds
  },
}))

No further changes are required if you used the generator. Verify this block is present before continuing.

Webpack projects

Add devtool to your webpack config:

// webpack.config.js
module.exports = (env, argv) => ({
  devtool: argv.mode === 'development' ? 'source-map' : false,
  // ...rest of your config
})

Manual / no-bundler projects

If you are not using a bundler, your source files are already loaded directly — no additional configuration is required.

Step 2: Start Dev-Watch Mode

The dev-watch npm script builds your tool in development mode and then watches for file changes, rebuilding automatically whenever you save:

npm run dev-watch

Leave this terminal open while you work. Every time you save a source file you will see a new build complete message:

✓ built in 312ms
watching for file changes...

Step 3: Enable Debug Menu in PPTB

The debug loader is hidden by default. To reveal it:

1. Open Power Platform ToolBox
2. Click the Settings gear icon in the sidebar
3. Toggle on Show Debug Menu
4. Click Save

A Debug section now appears in the sidebar.

Step 4: Load Your Tool for Debugging

1. In the sidebar, click Debug
2. Under Load Local Tool, click Browse
3. Navigate to and select your tool's root directory (the folder that contains package.json)
4. Click Load Tool

Your tool opens in a new tab inside PPTB, loaded directly from the local dist/ folder.

To pick up changes after a rebuild, close the tool tab and click Load Tool again — there is no hot-reload; you must reload manually.

Step 5: Open DevTools

Each tool runs in its own sandboxed webview. To open DevTools for your tool:

1. With the tool tab active, go to the Help menu in PPTB
2. Select Toggle Tool DevTools

A Chromium DevTools window opens, attached to your tool's webview.

Step 6: Debug with DevTools

Navigating to your source files

1. In DevTools, open the Sources panel
2. In the file tree on the left, expand the origin that matches your tool (it will appear as a file:// path pointing to your dist/ directory)
3. Because source maps are enabled, you will also see a webpack:// or vite:// virtual entry that mirrors your original source tree — open files from there to work with readable TypeScript

Setting breakpoints

1. Open a source file in the Sources panel
2. Click the line number to the left of any statement to set a breakpoint (a blue marker appears)
3. Trigger the code path in your tool — execution will pause at the breakpoint
4. Use the toolbar buttons to step over, step into, or resume execution

Inspecting variables

While paused at a breakpoint, the Scope panel on the right shows all in-scope variables and their current values. You can also hover over any variable in the source view to see its value inline.

Using the Console

The Console panel gives you a live REPL in the context of your tool's webview:

// Try the PPTB APIs directly
const conn = await toolboxAPI.connections.getActiveConnection()
console.log(conn)

// Inspect the DOM
document.querySelector('#app')

All console.log, console.error, and console.warn calls from your tool's code appear here. Use them as lightweight tracing when you do not need to pause execution:

// app.ts
async function initialize() {
  console.log('[my-tool] initialize called')
  const connection = await toolboxAPI.connections.getActiveConnection()
  console.log('[my-tool] active connection:', connection)
  // ...
}

Network panel

Use the Network panel to inspect all HTTP requests made by your tool, including Dataverse API calls. You can verify:

• Request URL and HTTP method
• Request and response headers
• Response payload (JSON body)
• Timing information

Complete E2E Debugging Cycle

The following is the full end-to-end workflow to use when investigating a bug or developing a new feature:

1. Configure your build (one-time)

Verify vite.config.ts emits source maps in development mode (see Step 1).

2. Start watch mode

npm run dev-watch

3. Enable the debug menu (one-time)

Settings → toggle Show Debug Menu → Save.

4. Load your tool

Debug sidebar → Load Local Tool → Browse → select project root → Load Tool.

5. Open DevTools

Debug sidebar → Open DevTools for Active Tool.

6. Reproduce the issue

Interact with your tool until the bug is triggered or the feature code runs.

7. Inspect and fix

• Set breakpoints in the Sources panel
• Use the Console to query live state
• Check the Network panel for unexpected API responses

8. Edit source and rebuild

Save your changes in your editor. The dev-watch process rebuilds automatically:

✓ built in 312ms

9. Reload the tool

Close the tool tab in PPTB, then click Load Tool again. DevTools will need to be reopened after each reload.

10. Repeat steps 6–9 until the issue is resolved.

11. Produce a production build

When you are satisfied, stop the watch process and build for release:

npm run build

Verify the production build works correctly in PPTB before publishing.

Troubleshooting

Source files do not appear in DevTools Sources panel

• Confirm that sourcemap: true (or sourcemap: mode === 'development') is set in your build config
• Ensure you ran npm run dev-watch (not npm run build) before loading the tool
• Check the Sources panel for a webpack:// or vite:// virtual folder — source maps may be present but collapsed

Tool does not reflect my latest changes

• Check the dev-watch terminal for build errors that may have prevented a successful rebuild
• Close the tool tab and click Load Tool again — the loader does not hot-reload

DevTools shows minified code even with source maps

• Confirm you are loading files from the Sources panel's virtual source-map folder, not the compiled dist/ files directly
• Ensure your bundler is not applying minification in development mode (Vite does not minify by default when mode === 'development')

Breakpoints are not hit

• Make sure the breakpoint is set in the source-mapped file (under vite:// or webpack://), not in the raw compiled output
• Verify the code path is actually being executed — add a console.log just before the breakpoint to confirm