Publishing Your Tool

Once you've tested your tool locally and are ready to share it with the community, follow this guide to publish it to npm and submit it to the ToolBox registry.

Prerequisites

Before publishing, ensure your tool:

• ✅ Builds successfully without errors
• ✅ Has been tested in local debug mode
• ✅ Passes local validation with pptb-validate (see Local Tool Validation)
• ✅ Follows the Tool Development Guide
• ✅ Has complete package.json metadata
• ✅ Has appropriate license (open source recommended)
• ✅ Has documentation (README.md)

Step 1: Prepare Your Package

Update package.json

Ensure all required fields are present:

{
  "name": "@your-org/your-tool-name",
  "version": "1.0.0",
  "displayName": "Your Tool Name",
  "description": "Clear, concise description of what your tool does",
  "main": "index.html",
  "icon": "icons/test.svg",
  "license": "MIT",
  "contributors": [
    {
      "name": "Your Name",
      "url": "https://yourwebsite.com"
    },
    {
      "name": "Additional Contributor(s)"
    }
  ],
  "configurations": {
    //Where your tool's source code lives and is used in the help menu of the app
    "repository": "https://github.com/yourusername/your-tool",
    //Optional
    "website": "https://the tool website or documentation URL",
    // This is used to display the README in ToolBox, and must be hosted
    // on raw.githubusercontent.com (optional but recommended)
    "readmeUrl": "https://raw.githubusercontent.com/yourusername/your-tool/refs/heads/main/README.md"
  },
  "cspExceptions": {
    //This is an optional section, do not include unless your tool needs to connect to more than dataverse endpoints
    "connect-src": [
      {
        "domain": "www.api.example.com",
        "exceptionReason": "Explain **why** your tool needs this exception.",
        "optional": false // set to true if the core tool works without this exception
      }
    ]
  },
  "features": {
    // Optional section to declare special features your tool needs
    "multiConnection": "optional", // or "required" if your tool needs multiple connections
    "minAPI": "1.2.0" // minimum supported ToolBox API version
  }
}

Including Your Icon in dist/

Your SVG icon must be present in the dist/ folder after building. How you achieve this depends on your build setup.

No Bundler (manual copy)

Use shx for a cross-platform copy that works on Windows, macOS, and Linux:

npm install --save-dev shx

Then wire up individual copy steps and call them from your build script:

{
  "scripts": {
    "build": "tsc && npm run copy-html && npm run copy-css && npm run copy-icon",
    "copy-html": "shx cp src/index.html dist/",
    "copy-css": "shx cp src/styles.css dist/",
    "copy-icon": "shx cp -r icon/ dist/icon/"
  }
}

Adjust the paths to match your project structure. The copy-icon step recursively copies your entire icon/ folder into dist/icon/, so whatever path you reference in package.json's icon field (e.g., icon/test.svg) will be available after the build.

Vite

Vite automatically copies everything inside the public/ directory to dist/ at build time — no plugin required. Place your icon there:

public/
  icon/
    test.svg

If your public/ folder is in a non-default location, point Vite to it via publicDir:

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

export default defineConfig({
  publicDir: 'public', // default — change this if your folder is elsewhere
})

Your package.json icon field should then be icon/test.svg, which will resolve to dist/icon/test.svg after the build.

Webpack

Webpack has no built-in public folder, but you can achieve the same result by placing your icon under public/ and using copy-webpack-plugin to copy that folder to dist/:

npm install --save-dev copy-webpack-plugin

// webpack.config.js
const CopyPlugin = require('copy-webpack-plugin')

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: 'public', to: '.' },
      ],
    }),
  ],
}

With your icon at public/icon/test.svg, it will be output to dist/icon/test.svg, matching the icon field in package.json.

Step 2: Build Your Tool

Build your tool to create the distributable files:

npm run build

Verify that your dist/ directory contains:

• index.html (entry point)
• icons/test.svg (or similar SVG path referenced by top-level icon)
• All compiled JavaScript/CSS files
• Any required assets (images, icons, etc.)

Step 3: Validate Locally

Before finalizing and publishing, run the pptb-validate CLI to check your package.json against the same rules used by the official review pipeline:

npm run validate

Or without a script entry:

npx pptb-validate

Fix any errors reported before proceeding. Warnings indicate optional-but-recommended fields that are absent or misconfigured — address them where possible.

Step 4: Finalize Package

Run the finalization script to prepare your package:

npm run finalize-package

This ensures your package is ready for npm with correct file structure and dependencies.

Step 5: Publish to npm

First-Time Setup

If you haven't published to npm before:

# Create npm account (if needed)
npm login

Publish Your Package

# For scoped packages
npm publish --access public

# For unscoped packages
npm publish

Verify Publication

Check that your package is live:

npm view @your-org/your-tool-name

Or visit: https://www.npmjs.com/package/@your-org/your-tool-name

Step 6: Test Published Version

Before submitting to the registry, test your published npm package:

1. Open Power Platform ToolBox
2. Navigate to Debug section
3. In "Install from npm" section:
   • Enter your package name: @your-org/your-tool-name
   • Click Install
4. Test thoroughly to ensure everything works as expected

Step 7: Submit to ToolBox Registry

Once your tool is working correctly from npm:

Fill Out the Tool Submission Form

Visit the Tool Submission Form (you need to login) and provide:

Automated Validation

After submission, automated checks will validate:

• ✅ npm package exists and is accessible
• ✅ Package contains appropriate metadata
• ✅ License is appropriate (open source preferred)
• ✅ No known security vulnerabilities
• ✅ Package structure is correct

Manual Review

Maintainers will review your submission for:

• Security (no malicious code)
• Quality (follows guidelines)
• Functionality (works as described)
• Documentation (README is clear)

Review typically takes 48-72 hours.

Versioning and Updates

Semantic Versioning

Follow Semantic Versioning:

• Patch (1.0.X): Bug fixes

  npm version patch
  

  CopyCopied!

• Minor (1.X.0): New features (backward compatible)

  npm version minor
  

  CopyCopied!

• Major (X.0.0): Breaking changes

  npm version major
  

  CopyCopied!

Publishing Updates

# Update version
npm version patch  # or minor, or major

# Build
npm run build

# Publish
npm publish --access public

Best Practices

Before Publishing

• ✅ Test thoroughly in debug mode
• ✅ Run pptb-validate and fix all errors before publishing
• ✅ Write comprehensive README with usage instructions
• ✅ Include screenshots or demo GIFs
• ✅ Document all features and limitations
• ✅ Add proper error handling
• ✅ Follow UI/UX guidelines for consistency

After Publishing

• ✅ Monitor GitHub issues for bug reports
• ✅ Respond to user feedback promptly
• ✅ Keep dependencies up to date
• ✅ Maintain a CHANGELOG
• ✅ Provide migration guides for breaking changes
• ✅ Consider semantic versioning strictly

Security

• ⚠️ Never include hardcoded credentials or API keys
• ⚠️ Validate all user inputs
• ⚠️ Use HTTPS for external API calls
• ⚠️ Don't access sensitive system resources
• ⚠️ Follow principle of least privilege

Troubleshooting

npm publish fails

Error: You must be logged in to publish packages.

Solution:

npm login
# Re-try publish

Error: Package name too similar to existing package.

Solution: Choose a more unique name or use scoped naming: @your-org/tool-name

Tool not appearing in registry

Check:

1. Ensure automated validation passed
2. Check submission issue for maintainer feedback
3. Verify npm package is publicly accessible
4. Confirm package.json has all required fields

Users reporting issues

Steps:

1. Reproduce the issue in debug mode
2. Fix in your local version
3. Update version number
4. Publish update to npm
5. Notify users in the issue thread

Next Steps

Support

Need help publishing your tool?

• GitHub Discussions: Ask the community
• Issues: Report problems
• Documentation: Full tool dev guide