Skip to main content
A company Widget Package lives in a generated portal project. The project registers its packages in src/widgets.config.ts and publishes their runtime artifacts with the portal CLI.

Before you start

Confirm the target company, Portal app, screen and package owner before changing anything. A company widget belongs in a Portal project; a Droplet receiver is a separate backend and does not become a Portal widget when deployed. See choose a package model. Open the Portal project as the agent’s working project. Check its package manager, lockfile, installed SDK and available scripts. Install dependencies with the project’s package manager before running checks. If the agent cannot access the folder or install dependencies, report the exact missing step; do not create another Portal app as a workaround. For Droplet reads, follow Portal Droplet data. Confirm the installed SDK exports the required function, the Portal host supports it, and the receiver implements the chosen operation and response shape. An operation such as member.echo is application-defined; do not substitute it for a receiver’s existing member.whoami operation.

Create a widget

From the portal project root:
The widget name must use kebab case. Use --category when it belongs in a builder palette category other than components.

Define the package

The scaffold adds widget source and updates src/widgets.config.ts. Import worker APIs only from:
Keep package identity, widget registrations, defaults, property schemas, and declared uses together in the package definition. See defineWidget and defineWidgetPackage for the exact authoring contracts.

Preview and validate

Preview the widget through the portal host. Verify empty data, keyboard use, focus, theme modes, and narrow layouts.

Check publication without writing

The dry run builds and validates the package without publishing it.

Publish company widget artifacts

This command publishes company widget runtime artifacts from src/widgets.config.ts. It does not push Portal Definition JSON or activate a portal version.
After publication, place the published widget through the supported portal authoring flow. Portal JSON and Widget Package definitions remain separate contracts.

Place, approve and publish

  1. Open the intended Portal app and screen in the builder. Find the current widget in Widgets and add it to the screen.
  2. Review the publisher, package version and requested permissions. Choose Allow capabilities only for the intended package and permissions. Declaring uses does not grant access.
  3. Save the draft. Publish the intended Portal changes only when authorized. Publishing package artifacts and publishing the Portal are separate steps.
  4. Open the actual Portal URL as a signed-in member. Confirm the widget renders and makes its intended host call. A build, dry run or successful stylesheet download does not prove the integration works.
Approval matches the package ID, package version and capability version. After a package update, an existing placement can retain an older grant. Use the supported builder flow to remove and re-add the current widget, approve it, then save and publish when ready. Check every placement, including duplicate instances. Never hand-edit capability grants.

Verify and hand off to an AI agent

Keep the Portal tab focused during the first live test. Test loading, success, empty results and unavailable states. For private data, also test sign-out and account switching; previous member data must not remain visible in the next session. Preview unavailability is not proof that the live integration fails. Report each stage separately: source created, checks passed, package registered with its exact version, widget placed, capabilities approved, draft saved, Portal published and live behavior verified. Mark unfinished stages as pending and name the next action. Do not say “deployed and verified” when only the receiver or package artifacts are deployed. Use this task prompt:
Build a company-scoped Portal widget in the intended Portal project. Follow the company quickstart and troubleshooting guide. Verify the installed SDK, declare the required portal functions, and validate the actual data contract. Run the project’s checks and publication dry run. Register the package when authorized, then report its exact version and the remaining builder approval, placement and Portal publication steps. Test the actual Portal UI and host call before claiming completion. Keep secrets and member payloads out of diagnostic reports.
For failures, start with Widget Package troubleshooting.