https://github.com/wasabithumb/minimessage-js
Lenient MiniMessage parser and HTML serializer made in TypeScript
https://github.com/wasabithumb/minimessage-js
html javascript minecraft minimessage rich-text text-component typescript
Last synced: 3 months ago
JSON representation
Lenient MiniMessage parser and HTML serializer made in TypeScript
- Host: GitHub
- URL: https://github.com/wasabithumb/minimessage-js
- Owner: WasabiThumb
- License: apache-2.0
- Created: 2024-07-31T21:16:57.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-05-22T18:45:24.000Z (11 months ago)
- Last Synced: 2025-06-07T16:14:36.694Z (11 months ago)
- Topics: html, javascript, minecraft, minimessage, rich-text, text-component, typescript
- Language: TypeScript
- Homepage:
- Size: 17.7 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# minimessage-js
[Source Code](https://github.com/WasabiThumb/minimessage-js/) | [NPM Page](https://www.npmjs.com/package/minimessage-js) | [Web Demo](https://wasabithumb.github.io/minimessage-js/)
A TypeScript reimplementation of
some [adventure](https://github.com/PaperMC/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
```js
import { MiniMessage } from "minimessage-js";
// OR: const { MiniMessage } = require("minimessage-js");
const mini = MiniMessage.miniMessage();
const component = mini.deserialize(`hello world!`);
```
### Browser
#### Module
```html
import { MiniMessage } from "minimessage.esm.js";
const mini = MiniMessage.miniMessage();
const component = mini.deserialize(`<rainbow>hello world!</rainbow>`);
mini.toHTML(component, document.querySelector(`#output`));
```
#### CommonJS
```html
// 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`));
```
## 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](#dom-effects))
or render to an HTML source string.
> [!CAUTION]
> Passing a string generated by ``toHTML`` into an element's ``innerHTML`` property
> is unadvisable. While the HTML renderer does properly escape content, this
> is an inefficient approach that indeed poses a remote security risk.
```ts
// Render to string
const html = mini.toHTML(component); // ...
// 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame) callback.
If successful, special rendering is activated.
| Tag | Effect |
|:----------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| ```` | Binds the "enchantment table" font to the document, assigns it to the obfuscated text, and randomizes the text content. |
| ```` | Asynchronously renders the appropriate player head using the [CORSjang](https://corsjang.b-cdn.net/) api. The 9 [default skins](https://minecraft.wiki/w/Skin#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>](https://docs.papermc.io/adventure/minimessage/format/#translatable)).
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.
```ts
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); // Diamond Block
```
## License
```text
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.
```