Skip to main content

Running & Versioning Your Widget

The Invent Claude skills handle scaffolding, MR creation, and deployment automatically. What's left for you to do by hand is running the widget locally during development and managing its versions in the ICP (Invent Control Panel).

Most of your day-to-day work happens against a real portal using Module Federation mode — this is the primary dev loop. A standalone dev mode also exists for early UI iteration but is rarely the right tool once your widget is connected to the platform.

Federation Mode — develop against a real portal​

This is how you'll spend almost all of your dev time. Your widget runs on your machine, your portal loads it from localhost, and you see your changes in the real platform environment — real data, real APIs, real other widgets.

Before you start​

Make sure your widget has been added to your portal — this happens at the end of Step 5 of the AI Quickstart Getting Started, when the Invent Technical team registers it. You should also have received the URL of your portal from the Invent team in Slack; wherever this guide says "open your portal," that's the URL it's referring to.

Once your widget is registered, the portal serves it as the latest deployed version by default. To develop locally, you'll add it to a dashboard, then switch it to dev-version in the ICP so the portal loads it from your machine instead.

Step 1 — Add your widget to a dashboard​

Open your portal in the browser and:

  1. Open a dashboard (or create one).
  2. In the Dashboard Composer, click Add micro app.
  3. Find your widget in the Micro App Library and add it to the dashboard.

The widget will load using its latest deployed version. Reload to confirm it appears.

Step 2 — Switch the widget to dev-version in the ICP​

This tells the portal to load your widget from localhost instead of the deployed bundle.

  1. Open the ICP (Invent Control Panel). You'll see a list of portals you have access to.
  2. Click the portal you want to develop against — the one matching the URL the Invent team shared with you.
  3. Open the Micro Apps Versioning tab.
  4. Find your widget in the list. Click the cog icon (⚙️) next to it.
  5. In the Change Current Version dropdown, select dev-version.
  6. Click Apply.
note

Dev mode only loads on your own machine. When the version is set to dev-version, the portal tells each user's browser to load the widget from localhost. Since localhost resolves to whatever's running on that user's computer, only you (with npm run start_federation running) actually see the dev build. Anyone else viewing the same portal will see a "Cannot load widget" error in the widget's place — their browsers have nothing to fetch from.

You still need to switch the version back once you're done so the widget loads for everyone:

  • latest — the portal will auto-update to whatever the most recent release is. Use this when you want the portal to always stay current.
  • A specific version (e.g. 1.2.3) — pins the portal to that exact version. Use this when you need stability or a controlled rollout.

Step 3 — Run the dev server​

In your terminal, from the root of your widget repo:

npm run start_federation

The widget builds for federation and serves on its dev port (e.g. localhost:5123). Hot Module Replacement (HMR) is enabled and source maps are available.

Step 4 — Develop​

  • Back in your portal, reload the dashboard. The widget now loads from your local dev server.
  • Make code changes. Reload the page to see them.
  • Debug with browser DevTools — source maps work, so you'll see your real source files.

When you're done, swap the ICP version back to latest (or pin a specific version — see below) so other users aren't trying to load your local server.

Version Management (ICP)​

The platform handles version bumps automatically once your code is merged — the gitlab-mr skill ensures the MR title carries the right semantic tag (feat: / fix:), and semantic-release cuts a new version when the MR is merged. You don't have to do anything to publish.

What you may need to do in the ICP is decide which version each portal uses:

Latest version (default)​

When your widget is first added to a portal, it's pinned to latest — every new release auto-rolls out. For most teams this is what you want; the AI Quickstart Step 5 flow puts you in this state.

Pinning a fixed version​

If a portal needs to stay on a specific version (regression hold, staged rollout, etc.):

  1. Open the ICP. You'll see your list of portals.
  2. Click the portal you want to pin.
  3. Open the Micro Apps Versioning tab.
  4. Find your widget. Click the cog icon (⚙️).
  5. In the Change Current Version dropdown, select the version you want.
  6. Click Apply.

The portal stops auto-updating and stays on the version you picked.

If your widget isn't listed in Micro Apps Versioning​

This means the widget hasn't been registered to your portal yet. After the initial setup completes and the pipeline runs successfully, you need to message the Invent Technical team on Slack so we can add it to your portal — see AI Quickstart → Step 5: Notify the Team & View Your App. Once we've registered it, it will appear in Micro Apps Versioning.

Standalone dev mode (npm run dev)​

Expand for details

For pure UI work without any platform integration, you can run the widget standalone:

npm run dev

This uses src/main.tsx as the entry point and src/local-widget.tsx for mocked props (theme, httpClient, platformMeta, etc.). Useful when:

  • You're sketching out the initial UI before the widget is registered with a portal.
  • You're offline or the portal is down.
  • You want to iterate on layout without the cognitive overhead of a full dashboard.

For anything that actually exercises platform APIs — auth, data fetching, state sharing, other widgets — switch back to federation mode. The mocks in local-widget.tsx only cover the surface and quickly diverge from real platform behavior.