The Widget Registry is a project that allows you to maintain a registry of JavaScript applications. The goal of this project is to be able to register your JS application (React, Vue, vanilla JS, ...) so it can be discoverable and embedded in other places easily.

Check the schema documentation. This contains help of how to use each one of the properties in the registry JSON file.

The goal of this project is to give you the ability to create your own independent widget registry and host wherever you want. We recommend starting with GitHub pages for ease of setup. All the computation is done via CI, that means that you can host your widget registry in an static site hosting like GitHub Pages (free!), AWS S3, your own server, etc.

The compiler will:

1. Inspect all the JS apps (aka widgets) registered in /metadata/registry.json.
2. Download the tarball of every application for the specified version.
3. Execute npm install && npm run-script build on the downloaded applications.
4. Place all the application bundles in a new folder called /dist.
5. Compute some additional needed metadata and store it in /dist/registry.json.

From there you decide where to upload the contents of /dist.

Once everything is compiled, you will need to upload the generated files to a server of you choice (read some suggestions further below). The /dist/registry.json will contain all the info your CMS will need to embed the JS app.

For instance, I can have GitHub Actions upload it to my personal server after finishing compilation. It could end up in https://static.mateuaguilo.com/widgets/registry.json. This URL is all your CMS needs to discover all the available apps and allow you to embed them anywhere.

Our recommendation is to fork this project and start from there. The Widget Registry boilerplate contains:

• CI processes (using GitHub Actions) that compile the registry after changing /metadata/registry.json on the main branch.
• CI processes (using GitHub Actions) that upload the resulting registry into GitHub Pages to make it available to Drupal, Wordpress, SquareSpace, static HTML, etc.
• Configuration management, so you can have a sandbox environment to do your tests.

You can for the project and use what you need from it. If you prefer using Circle CI for the continuous integration and deployment, that is perfectly reasonable. The choices made in the boilerplate are the best for the majority of cases, but you can go any other route to meet your particular project needs.

The only input in the Widget Registry is the /metadata/registry.json. This contains an array of objets. Each object has the necessary metadata to compile a widget:

1. The shortcode or machine name of the widget. This is the widget identifier.
2. The version that needs to be published. Once the widget has been published for the first time, it is likely that this is the only parameter that needs to be tweaked (via a Pull Request to your own widget registry project) to publish a new release of the JS app.
3. The repositoryUrl or tarballUrl. If you are hosting your JS app in GitHub and you are using GitHub Releases you can set repositoryUrl and be done. The compiler will know how to locate and download your application's .tar.gz tarball. If you are hosting your application releases differently, you will need to use the tarballUrl property to specify where the .tar.gz file is for this version of your application. This can be a local path or a remote URL.
4. The status of the widget. With allowed values of (stable|beta|wip|deprecated) it will show in the widget registry and in the catalog if a widget is ready to embed in production.

The tarballUrl has you covered, but you might want to automate the computation of the tarballUrl. If you want to provide support for other technologies (GitLab releases, particular naming conventions, etc.) you can write a plugin like these.

You will need to determine a new property (ex: gitlabRepo) and implement the logic to determine the URL to the tarball.

You can keep these plugins to yourself, but if you think it can benefit others we encourage you to contribute it.

Check the Widget Registry Boilerplate and the Example Widget. With a for loop and a few clicks you can have a quick demo up to test in your Drupal site.

The integration with Drupal is provided by:

• Widget Instance module. This will allow you to render the JS application anywhere you can use a content entity (rendered as an entity reference, as a block, ...).
• Widget Ingestion module. This will periodically check for new widgets and new versions using the widget registry URL (ex: this one).