Package Manifest

Every Power Platform ToolBox tool requires a package.json file at the root of the distribution. This file describes your tool to the ToolBox host and the npm registry.

iconURL under configurations is no longer supported. Use the top-level icon field instead with an SVG path relative to your dist root.

Overview

The package.json follows the standard npm package format with additional PPTB-specific fields. Required fields must be present for your tool to load correctly.

Required Fields

Field	Type	Description	Sample
`name`	`string`	Scoped npm package name — lowercase, no spaces	`"@myorg/my-tool"`
`version`	`string`	SemVer-compatible version	`"1.0.0"`
`displayName`	`string`	Human-readable name shown in the ToolBox UI	`"My Awesome Tool"`
`description`	`string`	Short description of what the tool does	`"Manage Dataverse solutions"`
`main`	`string`	Entry-point file relative to the `dist` root	`"index.html"`
`icon`	`string`	Path to SVG icon relative to the `dist` root. Use `fill="currentColor"` to support light/dark themes	`"icons/tool.svg"`
`license`	`string`	An approved open-source license identifier	`"MIT"`
`contributors`	`array`	One or more objects with a `name` and optional `url`	See below
`configurations`	`object`	PPTB-specific links and metadata	See Configurations Object

`contributors` array

Each entry must have at minimum a name.

"contributors": [
  { "name": "Jane Dev", "url": "https://janedev.com" },
  { "name": "John Doe" }
]

Allowed licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, GPL-2.0, GPL-3.0, LGPL-3.0, ISC, AGPL-3.0-only.

Configurations Object

Nested inside the top-level configurations key.

Field	Required	Type	Description	Sample
`repository`	Yes	`string`	URL of the tool's source repository — shown in the ToolBox help menu	`"https://github.com/myorg/my-tool"`
`website`	No	`string`	Tool website or documentation URL	`"https://docs.myorg.com/my-tool"`
`readmeUrl`	No	`string`	Raw `githubusercontent.com` URL for the README — used to display docs inside ToolBox	`"https://raw.githubusercontent.com/myorg/my-tool/main/README.md"`

Optional Fields

Field	Type	Description	Sample
`homepage`	`string`	Public homepage URL	`"https://myorg.com"`
`repository`	`object`	Standard npm repository object	`{ "type": "git", "url": "https://github.com/…" }`
`cspExceptions`	`object`	Additional Content Security Policy origins your tool connects to	See CSP Exceptions Object
`features`	`object`	Declare special ToolBox capabilities required by your tool	See Features Object

Features Object

Declare ToolBox-specific capabilities your tool needs. Omit this section entirely if neither field applies.

Field	Type	Values	Description	Sample
`multiConnection`	`string`	`"optional"` \| `"required"`	Whether the tool supports or requires a second Dataverse connection	`"optional"`
`minAPI`	`string`	SemVer	Minimum ToolBox API version the tool requires	`"1.2.0"`

"features": {
  "multiConnection": "optional",
  "minAPI": "1.2.0"
}

Specifying a Minimum API Version

The minAPI field lets you declare the lowest ToolBox API version your tool is compatible with. When a user installs or opens your tool, Power Platform ToolBox checks this value against the currently installed ToolBox version. If the installed version is older than the minimum required, ToolBox will alert the user and recommend upgrading before they can use the tool.

When to set minAPI:

Your tool calls an API or uses a feature that was introduced in a specific ToolBox release (for example, multiConnection requires 1.2.0 or later).
You want to prevent runtime errors caused by a user running an older, incompatible version of ToolBox.

How to determine the correct value:

Each function in the API Reference includes a Requires vX.Y.Z badge showing the minimum ToolBox version it needs (where applicable). Set minAPI to the highest such version across all the functions your tool depends on.

You only need to set minAPI if your tool relies on features that were not available in the very first public release. If your tool only uses core APIs that have been available from the start, you can omit this field.

Setting minAPI too high (higher than necessary) will prevent users with older but compatible ToolBox versions from running your tool. Always use the lowest version that includes all the features you actually need.

CSP Exceptions Object

Declare additional external origins that your tool's iframe is permitted to connect to. Omit this section entirely if your tool only communicates with Dataverse endpoints. All fields are optional.

Each directive accepts an array of entries. An entry can be either a plain string (just the domain) or an object with the following properties:

Field	Type	Required	Description	Sample
`domain`	`string`	Yes	The origin/domain to allow	`"api.example.com"`
`exceptionReason`	`string`	No	Markdown description explaining why this CSP exception is needed. Displayed to users in the consent dialog.	`"Used to read configuration details."`
`optional`	`boolean`	No	When `true`, indicates the exception is optional — the core tool works without it, but granting it enables additional functionality. Defaults to `false`.	`true`

The supported CSP directives are:

Directive	Description	Sample domain
`connect-src`	Fetch, XHR, WebSocket, and EventSource origins	`"api.example.com"`
`script-src`	Additional origins allowed to serve scripts	`"cdn.example.com"`
`style-src`	Additional origins allowed to serve stylesheets	`"fonts.googleapis.com"`
`img-src`	Additional origins allowed to serve images	`"img.example.com"`
`font-src`	Additional origins allowed to serve fonts	`"fonts.gstatic.com"`
`frame-src`	Origins allowed to be embedded in iframes	`"embed.example.com"`
`media-src`	Origins allowed to serve audio/video media	`"media.example.com"`

"cspExceptions": {
  "connect-src": [
    {
      "domain": "api.example.com",
      "exceptionReason": "Used to **fetch** live data for the dashboard."
    }
  ],
  "script-src": [
    {
      "domain": "cdn.example.com",
      "exceptionReason": "Loads the charting library used to render reports."
    }
  ],
  "style-src": [
    {
      "domain": "fonts.googleapis.com",
      "exceptionReason": "Provides the UI font family.",
      "optional": true
    }
  ],
  "img-src": ["img.example.com"],
  "font-src": ["fonts.gstatic.com"],
  "frame-src": ["embed.example.com"],
  "media-src": ["media.example.com"]
}

Only add origins you genuinely need. Unnecessary CSP exceptions will be flagged during registry submission review.

Full Example

{
  "name": "@myorg/my-awesome-tool",
  "version": "1.0.0",
  "displayName": "My Awesome Tool",
  "description": "Manage Dataverse solutions across environments with ease.",
  "main": "index.html",
  "icon": "icons/tool.svg",
  "license": "MIT",
  "contributors": [
    { "name": "Jane Dev", "url": "https://janedev.com" },
    { "name": "John Doe" }
  ],
  "configurations": {
    "repository": "https://github.com/myorg/my-awesome-tool",
    "website": "https://docs.myorg.com/my-awesome-tool",
    "readmeUrl": "https://raw.githubusercontent.com/myorg/my-awesome-tool/main/README.md"
  },
  "features": {
    "multiConnection": "optional",
    "minAPI": "1.2.0"
  },
  "cspExceptions": {
    "connect-src": [
      {
        "domain": "api.example.com",
        "exceptionReason": "Used to **fetch** live configuration data for the dashboard."
      }
    ],
    "img-src": [
      {
        "domain": "img.example.com",
        "exceptionReason": "Loads thumbnails for the media browser.",
        "optional": true
      }
    ]
  },
  "keywords": ["dataverse", "power-platform", "solutions"],
  "homepage": "https://docs.myorg.com/my-awesome-tool",
  "repository": {
    "type": "git",
    "url": "https://github.com/myorg/my-awesome-tool.git"
  },
  "bugs": {
    "url": "https://github.com/myorg/my-awesome-tool/issues"
  },
  "dependencies": {},
  "devDependencies": {
    "@pptb/types": "^1.0.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  },
  "scripts": {
    "build": "vite build",
    "dev": "vite"
  }
}