Updating MWDK to v3.x

How to Update to v3.x

MWDK v3 uses webpack 5 and express to host the dev kit locally. As before, a widget must implement a webpack.config.js with specific configurations required for it to compile, as well as the requisite script entries in the package.json.

NOTE: MWDK v3 uses Node v16 or higher, no longer 12.3.1.

Changes to package.json

The dev kit must be listed as a dependency (NOT a dev dependency!):

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

The scripts section must implement the following:

 "scripts": {
    "start": "mwdk-start",
    "build": "mwdk-build-prod",
    "build-dev": "mwdk-build-dev"
  },

Changes to webpack.config.js

The entries section has been modified. Now, entry indexes are simplified to player, creator, and scoreScreen respectively. Including guide files is no longer required. Include only entries that have HTML files (except for markdown files). Include the HTML file as the first element, then include any necessary JS and CSS after.

For example, this is the entries object for Enigma:

Previously:

const entries = {
	'creator.js': [
		path.join(__dirname, 'src', 'modules/creator.coffee'),
		path.join(__dirname, 'src', 'controllers/creator.coffee'),
		path.join(__dirname, 'src', 'directives/enter.coffee'),
		path.join(__dirname, 'src', 'directives/focus.coffee')
	],
	'player.js': [
		path.join(__dirname, 'src', 'modules/player.coffee'),
		path.join(__dirname, 'src', 'directives/scroll.coffee'),
		path.join(__dirname, 'src', 'controllers/player.coffee')
	],
	'creator.css': [
		path.join(__dirname, 'src', 'creator.html'),
		path.join(__dirname, 'src', 'creator.scss')
	],
	'player.css': [
		path.join(__dirname, 'src', 'player.html'),
		path.join(__dirname, 'src', 'player.scss')
	],
	'guides/guideStyles.css': [
		path.join(__dirname, 'src', '_guides', 'guideStyles.scss')
	],
	'guides/player.temp.html': [
		path.join(__dirname, 'src', '_guides', 'player.md')
	],
	'guides/creator.temp.html': [
		path.join(__dirname, 'src', '_guides', 'creator.md')
	]
}

With MWDK3.x:

const entries = {
	'player': [
		path.join(srcPath, 'player.html'),
		path.join(srcPath, 'modules/player.coffee'),
		path.join(srcPath, 'directives/scroll.coffee'),
		path.join(srcPath, 'controllers/player.coffee'),
		path.join(srcPath, 'player.scss')
	],
	'creator': [
		path.join(srcPath, 'creator.html'),
		path.join(srcPath, 'modules/creator.coffee'),
		path.join(srcPath, 'controllers/creator.coffee'),
		path.join(srcPath, 'directives/enter.coffee'),
		path.join(srcPath, 'directives/focus.coffee'),
		path.join(srcPath, 'creator.scss'),
	]
}

Addtionally, you may need to remove the following rules from moduleRules, if applicable: rules.loadAndCompileMarkdown andrules.loadAndPrefixCSS. For more info on the available rules, see the Rules section.

Changes to CSS

Either include CSS inside your JS files for Webpack to recognize them, or include them in your entries object.

Use absolute urls for assets like loading fonts

AngularJS Widgets

AngularJS widgets may encounter an angular injection error. This usually only occurs with widgets that have directives, services, and controllers loaded in separate files. There are two ways to fix this. One way is to set up the directives, controllers, and services in a single file. The other, more difficult way is to manually bootstrap the angular modules:

1. Remove ng-app from body or HTML tags.
2. Move the main scripts such as player.js and creator.js to the end of the body tag
3. Inside the files declaring the angular modules, remove the variable declaration when initially declaring the module. For example, the matching widget would look like:
4. At the very end of the last file in the respective webpack entry, manually start the module with the command: angular.bootstrap(document, ['your-module-name-here']). The example above would look like:

Github workflows

The GitHub workflows, if present, will need to be updated with newer versions of certain actions.

node-version references:

node-version: [12.x] => node-version: [18.13.0]

actions/checkout references:

actions/checkout@v2 => actions/checkout@v5

actions/setup-node references:

actions/setup-node@v1 => actions/setup-node@v3

For convenience, the current variations of both files are available on the GitHub Actions page of the wiki.

Widget URLs Change

As of MWDK v3.0.0, the urls for accessing the player and creator in the MWDK have changed. They now use the same urls as Materia.

Old URLs:

Creator: /mwdk/widgets/1-mwdk/create/(instance_id)

Player: /mwdk/player/(instance_id)

New URLs:

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

Player: /preview/(instance_id)