minimessage-js

Online Demo • NPM • GitHub • Spec

A deserializer mirroring the MiniMessage API, combined with an HTML renderer, in pure JS. Compare to minimessage-2-html, which works by sending web requests to the official webui.

Usage

NodeJS

// es6
import MiniMessage from "minimessage-js";
// cjs
const MiniMessage = require("minimessage-js");

const component = MiniMessage
        .miniMessage()
        .deserialize(`<rainbow>hello world!</rainbow>`);

component.getProperty("extra");
// [ { text: "h", color: "#ff0000" }, ... ]

const htmlCode = MiniMessage
        .toHTML(component);
// string containing HTML code

The API is also designed to be able to theoretically support DOM polyfills like JSDOM:

const { JSDOM } = require("jsdom");
const dom = new JSDOM();

const output = dom.document.createElement("p");
MiniMessage.toHTML(component, output, (tag) => dom.document.createElement(tag));

Browser

This package includes a browser build. Add minimessage.min.js to your document, and MiniMessage will be exposed as a global variable. Then the library can be used like NodeJS.

<script src="https://unpkg.com/minimessage-js@^1.1"></script>
<p id="out"></p>
<script>
  const component = MiniMessage
          .miniMessage()
          .deserialize('<rainbow>hello world!</rainbow>');
  
  MiniMessage.toHTML(
      component,
      document.querySelector("#out")
  ); // also returns the HTML code as a string
</script>

Translations

Translations can be registered, which will take effect when rendering to HTML. You can add your own translations or optionally require the vanilla translations:

• @minimessage-js/translations : Contains JSON of all Vanilla translations (huge)
• @minimessage-js/fetch-translations : Contains methods to fetch translations from the Mojang API at runtime

const MiniMessageTranslations =
        require("@minimessage-js/translations");

const mm = MiniMessage.builder()
    // Add American English translations
    .translations(
        MiniMessageTranslations.get("en-us")
    )
    // Add custom translations
    .translations({ "greeting": "Hello %s!" })
    .build();

const component = mm.deserialize("<lang:greeting:Paul> You are " +
        "holding a <lang:block.minecraft.diamond_block>!");

const html = MiniMessage.toHTML(component);
/*
<span>
    <span data-mm-translate="greeting" data-mm-with="[\"Paul\"]">
        Hello Paul!
    </span>
    <span> You are holding a </span>
    <span data-mm-translate="block.minecraft.diamond_block">
        Block of Diamond
    </span>
    <span>!</span>
</span>
*/

HTML Rendering

As mentioned above, this package has an extra method not found in the original API: MiniMessage.toHTML. This converts the parsed Component object into nested <span> tags, wtih attributes set to apply the Component data. You can also pass an HTMLElement, which will receive the tags in a way that may be more efficient than setting it through innerHTML. This also will cause obfuscated text to render properly. Here is an overview of how the implemented properties parse to HTML:

Color

style="color: #XXXXXX" is set on the target <span>. This also supports color literals through the following conversion:

| Key | Color | Hex Code | | :--------------: | :------------------------------------------------------: | :---------: | | black | | #000000 | | dark_blue | | #0000aa | | dark_green | | #00aa00 | | dark_aqua | | #00aaaa | | dark_red | | #aa0000 | | dark_purple | | #aa00aa | | gold | | #ffaa00 | | gray | | #aaaaaa | | dark_gray | | #555555 | | blue | | #5555ff | | green | | #55ff55 | | aqua | | #55ffff | | red | | #ff5555 | | light_purple | | #ff55ff | | yellow | | #ffff55 | | white | | #ffffff |

Decorations (except obfuscated)

A CSS style declaration property: value; is added to the target <span>'s style attribute.

| Name | Declaration | | :---------------: | :-------------------------------: | | bold | font-weight: bold | | italic | font-style: italic | | underlined | text-decoration: underline | | strikethrough | text-decoration: line-through |

MiniMessage also allows for decoration inversions, e.g. <!bold> or <u:false>. In this case, the appropriate property is set to normal or none only if it was previously set in a higher enclosure.

Obfuscation

The property data-mm-obfuscted is set to true on the <span>. If outputting to an HTMLElement, using in browser, the element is connected to the DOM, and 1 animation frame has ocurred, the content of the <span> is converted into <canvas> elements which will render the obfuscation effect.

Everything Else

Remaining properties propertyName will have data-mm-property-name set to a JSON string containing the value of the property if one is set. Examples:

| Property | HTML Attribute | Example Value | | :----------------------------------------------------------------------------: | :-----------------: | :------------------------------------------------------: | | clickEvent* | data-mm-click-event | { "action": "suggest_command", "value": "/kill @s" } | | hoverEvent* | data-mm-hover-event | { "action": "show_text", "contents": "hello!" } | | keybind* | data-mm-keybind | "key.jump" | | translate* | data-mm-translate | "block.minecraft.diamond_block" | | with (for translate) | data-mm-with | ["<red>1", "<blue>Stone!"] | | selector* | data-mm-selector | "@s" | | score* | data-mm-score | { "name": "@s", "objective": "kills" } | | insertion* | data-mm-insertion | "some text" | | font* | data-mm-font | "uniform" | | nbt* | data-mm-nbt | "entity" | | block (for nbt = "block") | data-mm-block | unknown (help wanted) | | entity (for nbt = "entity" ) | data-mm-entity | "@s" | | storage (for nbt = "storage") | data-mm-storage | unknown (help wanted) | | interpret (for nbt) | data-mm-interpret | false | | separator (for nbt) | data-mm-separator | "," |

Does it work?

minimessage-js uses output from the official WebUI to validate test cases. Over all implemented tags, no instance has been found where the 2 outputs do not fuzzy match. The main differences are:

• This library always hex-ifies color literals, e.g. red -> #ff5555, whereas MiniMessage tends to keep color literals unconverted.
• This library sometimes may not include the text property on empty Components, whereas MiniMessage tends to add an empty string.

What's missing?

Currently, there is no MiniMessageInstance.serialize. Since there is no way to create Components directly, it doesn't make much sense to include.

License

Copyright 2024 Wasabi Codes

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.