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
• ✅ 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",
  "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": [
      "websites that your tool needs to connect to, e.g.: www.api.example.com"
    ]
  },
  "features": {
    // Optional section to declare special features your tool needs
    "multiConnection": "optional" // or "required" if your tool needs multiple connections
  }
}

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)
• All compiled JavaScript/CSS files
• Any required assets (images, icons, etc.)

Step 3: 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 4: 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 5: 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 6: 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
• ✅ 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