Skip to content

Home

Jump to bottom
Cay Henning edited this page Apr 18, 2024 · 20 revisions

Materia Widget Development Kit

The MWDK is an NPM package that allows developers to make widgets independent of the Materia platform, with live reloading and a handful of additional features to facilitate faster development. Additional documentation related to the MWDK's features are available on the docs site.

Requirements:

  • Node v16 or later
  • Yarn

Installation

To install MWDK, run: yarn add materia-widget-development-kit

MWDK should then be listed under the dependencies section of your widget's package.json:

"dependencies": {
    "materia-widget-development-kit": "3.0.0"
  }

Note that this is a required dependency of all Materia widgets.

Additionally, the following entries must be added to the scripts section of your widget's package.json:

"start": "mwdk-start",
"build": "mwdk-build-prod",
"build-dev": "mwdk-build-dev",
  • mwdk-start: This starts the Express server in development mode.
  • mwdk-build-prod: This builds webpack in production mode. See the output in /build folder.
  • mwdk-build-dev: This builds webpack in development mode. See the output in /build folder.

NPM vs Yarn

While both may work, we do not maintain a NPM lockfile (package-lock.json or npm-shrinkwrap.json) in the repo. Therefore, we recommend using yarn.

Starting your widget

Run yarn start in the widget's root directory. The widget will be available at localhost:8118.

To change the port, update process.env.PORT by running export PORT=1234 before yarn start.

The default node environment is development. If you wish to change this to production, you may set process.env.NODE_ENV in a similar fashion by running export NODE_ENV=production before yarn start.

Installing to Materia

Use the Download Package option on either the Player or Creator page to either download a compiled .wigt file locally (it's just a .zip file, but renamed) or install directly to your local instance of Materia. This requires a currently running local instance of Materia in Docker.

Widget Authoring

Visit the Developing Materia Widgets section of our docs site for comprehensive documentation related to authoring a widget.

Updating from MWDK versions < 3.0

Visit our page detailing the changes required to implement MWDK v3.x in your widget.

Widget URLs Change

As of MWDK v3.0.0, you can access your widget using the same urls as Materia.

Creator: /mwdk/widgets/1-mwdk/create

Player: /mwdk/player/

Clone this wiki locally