minimessage-js
v2.0.1
Published
Reimplementation of MiniMessage and associated Adventure APIs in TypeScript
Maintainers
wasabithumbsReadme
minimessage-js
Source Code | NPM Page | Web Demo
A TypeScript reimplementation of some adventure APIs for the browser and Node. With this library, you can:
- Deserialize MiniMessage strings into text components
- Serialize text components into MiniMessage strings
- Render text components into HTML
Quick Start
NodeJS
import { MiniMessage } from "minimessage-js";
// OR: const { MiniMessage } = require("minimessage-js");
const mini = MiniMessage.miniMessage();
const component = mini.deserialize(`<rainbow>hello world!</rainbow>`);Browser
Module
<span id="output"></span>
<script type="module">
import { MiniMessage } from "minimessage.esm.js";
const mini = MiniMessage.miniMessage();
const component = mini.deserialize(`<rainbow>hello world!</rainbow>`);
mini.toHTML(component, document.querySelector(`#output`));
</script>CommonJS
<span id="output"></span>
<script src="minimessage.umd.js"></script>
<script>
// All exports are exposed in the "adventure" global
const { MiniMessage } = window.adventure;
const mini = MiniMessage.miniMessage();
const component = mini.deserialize(`<rainbow>hello world!</rainbow>`);
mini.toHTML(component, document.querySelector(`#output`));
</script>HTML Rendering
One utility unique to this library is the HTML renderer.
To render a component to HTML, use MiniMessage#toHTML.
You may either render to an element in the DOM (also see DOM Effects)
or render to an HTML source string.
[!CAUTION] Passing a string generated by
toHTMLinto an element'sinnerHTMLproperty is unadvisable. While the HTML renderer does properly escape content, this is an inefficient approach that indeed poses a remote security risk.
// Render to string
const html = mini.toHTML(component); // <span>...</span>
// Render to element (browser environment)
mini.toHTML(component, element);
// Render to element (DOM polyfill, e.g. JSDOM)
mini.toHTML(component, element, (tag) => document.createElement(tag));DOM Effects
When rendering to a DOM element in a browser environment, the library will attempt to bind rendering effects within a requestAnimationFrame callback. If successful, special rendering is activated.
| Tag | Effect |
|:----------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| <obf> | Binds the "enchantment table" font to the document, assigns it to the obfuscated text, and randomizes the text content. |
| <head> | Asynchronously renders the appropriate player head using the CORSjang api. The 9 default skins are also bundled as a fallback. |
| others | Sets a data-mm-misc property on the element containing the text component this element was rendered from. This property is reserved for future use. |
Translations
The HTML renderer may be configured to use a specified translation map
to resolve translatable components (e.g. <lang>).
To aid in this you may use the @minimessage-js/translations or @minimessage-js/fetch-translations library-
the former containing a snapshot of all available translation data for synchronous access, and the latter providing
a method to fetch translation data from Mojang APIs at runtime.
import { MiniMessage, Component } from "minimessage-js";
import { MinecraftTranslations } from "@minimessage-js/translations";
const mini = MiniMessage.builder()
.translations(MinecraftTranslations.get("en_us")) // American English
.build();
const translatable = Component.translatable("block.minecraft.diamond_block");
mini.toHTML(translatable); // <span>Diamond Block</span>License
Copyright 2026 Xavier Pedraza
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.