v4.md

miyagi v4

General

• miyagi is now an ES module.
• The minimum NodeJS version is now 20.11.0.
• Lots of minor bug fixes.

UI

• The menu has dedicated sections for design tokes, components and documentation.

  In the design tokens section, there are dedicated pages for colors, sizes and typography.

• miyagi is now using a presentation mode when creating a static build.

  The presentation mode hides information that is targeted to developers and often unnecessary for other interested parties. However, in both presentation and development mode, there is a toggle to switch between both modes.

  More information: The UI / Presentation vs Development mode

• The HTML and accessibility validations have been removed.

  You can run tools like this in your command line or CI, so miyagi can be less cluttered.

• The search now only shows the result, hiding all other entries in the menu, which makes it easier to navigate.

• The UI nows shows resolved mock data and it uses a file tree for both mock data and schema.

• The design of miyagi got slighty revised.

Configuration

• Theming miyagi got revised.

  Instead of passing lots of configuration options, you can now make use of the CSS custom properties miyagi uses internally. Also, the config.ui.theme definition changed slightly.

  More information: How-to / Theming the UI

• You can now pass an AJV import to miyagi if you want to use a specific JSON schema version.

  More information: How-to: Configuring the JSON Schema validator

• You need to pass your own render method to miyagi.

  Previously, miyagi used consolidate.js under the hood. That meant that all rendering engines, that are supported by consolidate.js worked out of the box with miyagi. That is not longer the case as we removed the dependency to consolidate.js. Instead you need to provide a render method via config.engine.render. For twing e.g. this could look as simple as:

  async render({ name, context, cb }) {
  	try {
  		return cb(null, await twing.render(name, context));
  	} catch (err) {
  		return cb(err.toString());
  	}
  }

  This also means that you neither have to pass config.engine.name and config.engine.options anymore nor does miyagi try to guess the engine if you do not provide the engine configuration.

• Component info files are deprecated.

  There were previously used to define a proper name for the menu. miyagi will now use the component name for the menu.

• You can now use two different file types for mock files.

  This can be helpful if you usually want to use e.g. yaml for static mock data, but also need JavaScript to write mock data that is dynamic or needs to be computed in some way.

• All component variants are now always rendered in an iframe.

  Previously, having them not rendered inside iframes required miyagi to load your CSS along-side miyagi's CSS which could lead to nasty visual bugs.

  This also means that config.components.renderInIframe has been removed.

JavaScript API

New methods

• createBuild()
• createComponent({ component: String, only?: string[], skip?: string[] })
• createMockData({ component: String })
• lintComponent({ component: String })
• lintComponents()

More information: JavaScript API

Removed methods:

• getNode

  Alternative approach

  If you need the behavior of this method, you could achieve it like this:

  ```
  	import { getHtml } from "@miyagi/core/api";
  
  	const {
  		success,
  		data: html,
  		message,
  	} = await getHtml({ component, variant });
  
  	if (success) {
  		const div = document.createElement("div");
  
  		div.innerHTML = html.trim();
  
  		if (div.childElementCount > 1) {
  			return div;
  		}
  
  		return div.firstElementChild;
  	}
  
  	console.error(message);
  	return null;
  ```
  

Mock data & schema files

• Reusable definitions in mock files.

  You can now create definitions via $defs in mock files and reference them in other mock files.

  More information: How-to / Writing mock data

• Improved output when the JSON schema validation fails.

  Previously, miyagi was sometimes a bit unspecific when the given mock data did not match the JSON schema. miyagi now prints the whole error object provided by AJV, giving you more information.

  • When creating schema files using the CLI or JS API, they now contain additionalProperties: false.

Other

• You can now add a dedicated documentation section.

  In this section, you can now create Markdown files with any name. The (formatted) file name will be used for the menu.

• New verbose mode for easer debugging.

  The verbose mode can be invoked with -v or --verbose in case something went wrong. Has not been implemented everywhere yet, so miyagi might not be very verbose in every situation. :-)