Skip to main content

Register a Custom React App

Goal​

Install a Custom React App into an environment by uploading its package, so the Platform Shell can load it as an app there.

Looking for how to build the app rather than install one? This page assumes the app already exists and has been packaged. Writing it — project setup, the Module Federation configuration, the app component, the Runtime SDK, testing, and packaging — is Build a Custom React App.

Prerequisites​

  • You are signed in to the Admin Control Center as a platform administrator.
  • A publisher and a solution owned by that publisher already exist.
  • The environment you are installing the app into is active.
  • You have the app's package — the .zip produced by npm run pack in the app's own project. It is usually written to that project's package/ folder and named after the app, for example par_sales_dashboard-2.0.1.zip.

Steps​

  1. Choose the environment the app should be installed in, from the selector in the top bar.
  2. Open Solutions, then open the solution the app belongs to.
  3. Select Custom Apps in the solution's left navigation. The page lists the apps this solution has already installed in the selected environment.
  4. Select New. A panel opens at the side of the screen.
  5. Choose the app's package file.
  6. Select Register custom app. The app appears in the list for that solution and environment, and on the environment's home page in the Platform Shell.

That is the whole form. The package already says what the app is called, which Module Federation scope it was built with, which module it exposes, and which scopes it needs — so there is nothing to type, and nothing to mistype.

What happens behind the scenes​

The platform checks the archive before storing anything: its size, how many files it holds, how far it expands, that no path escapes the folder, and that every file is a kind it will serve. It then reads the app's manifest out of the archive, validates it against the Custom App manifest schema, and checks the logical name against the owning publisher's prefix.

The archive is stored in the platform's own database, and the app's code is served from the platform's own address. That is what makes the solution self-contained: exporting it carries the code, so importing it into Test or Production installs a working app with no external host to keep running.

Installing the app in one environment does not install it in any other. It travels when its solution is exported and imported there.

Uploading again replaces the installed build. That is the normal loop while you are working: build, upload, look, build again.

Hosted mode, for development only​

While writing an app you can register it as Hosted instead: the Shell loads remoteEntry.js from your dev server, so you keep hot-reload and do not repackage for every change. The platform refuses a Hosted registration in any environment that is not a development environment, because an app whose code lives somewhere else is an app its solution cannot carry.

Troubleshooting​

  • "Custom app … must start with the publisher prefix …_." — the logicalName in the app's package.json does not begin with the owning publisher's prefix. Fix it there and rebuild the package; the name comes from the build, not from this screen.
  • "The package manifest is invalid: …" — the archive's parsware.json does not match the expected shape. It is written by parsware-pack, so this usually means the package was hand-edited or built by an older version of the tool.
  • "… holds a CustomControl, not a CustomApp." — this is a Custom Control's package. Install it from the Custom Controls page instead.
  • "Custom app … is already installed in this environment by another solution." — the name is taken by a different solution. Rename yours, or remove the other registration first.
  • "Environment … is not a development environment" — you are registering a Hosted app outside development. Upload the package instead.
  • "Environment … is not active." — wait until the environment finishes provisioning, or choose a different environment.
  • Build a Custom React App.
  • Open a Custom React App.
  • Register a Custom Control.
  • Create a solution.