mfm-vue

mfm-vue

Vue 3向けのMFMレンダラです。構文解析にはmfm.jsを利用しています。他実装とは異なり、Misskey本家との描画結果の互換性を重視しています。

特徴

• <Mfm>を通常のVueコンポーネントとしてimportして利用できます。app.use()やグローバル登録は不要です
• リンク, メンション, ハッシュタグ, 絵文字, コード, 数式などの描画を、コンポーネントまたはslotで差し替えることができます
• 独自関数の追加や組み込み関数の上書き・無効化をサポートしています
• AST変換は描画関数で行い構文ノードごとのコンポーネント生成を行っていません。リンク/絵文字等の描画部品はSFCで、SSRとハイドレーションに対応しています
• 各スタイルはすべてコンポーネント単位のscoped CSSで構成されており、グローバルセレクタやキーフレームで汚染することは(おそらく)ありません
• v-html/innerHTML未使用

インストール

pnpm add mfm-vue mfm-js vue

ビルド済みパッケージから利用する場合は、スタイルシートを一度だけ読み込む必要があります。(*中身は各コンポーネントのscoped CSSで、セレクタはすべてscope属性付きデす)

import "mfm-vue/style.css";

使い方

基本

<script setup lang="ts">
import { Mfm } from "mfm-vue";

const note = {
  text: "Hello **MFM** :misskey: $[tada 🎉] @ai #misskey",
  emojis: {},
  user: { host: null, isCat: false },
};
</script>

<template>
  <Mfm
    :text="note.text"
    instance-url="https://misskey.example"
    :author="note.user"
    :emoji-urls="note.emojis"
    nyaize="respect"
    @click-ev="(ev) => console.log(ev)"
  />
</template>

主要props

<Mfm>は次のイベントを送出します。

• clickEv(ev: string): $[clickable.ev=xxx ...]のクリック時
• copy({ text, success }): コードブロックのコピー時(provideMfmConfigではonCopyでも取得できます)

i18n

localeの完全一致(zh-twなど), 言語部分(ja-JPならja)で指定可能です。en, ja等はMisskeyの表記に準拠しています。そのほかzh, zh-TW, ko, fr, de, es, it, pt, ru, uk, pl, tr, id, th, vi, arを同梱しています。これらの言語の相対時刻はIntl.RelativeTimeFormatで表示されますが、サポートされていない言語はenの文言にフォールバックされるため、必要に応じてmessagesをoverrideしてください。

provideMfmConfig({
  locale: "fr-FR",
  messages: { search: "Rechercher", ago: { years: "il y a {n} ans" } },
});

コードハイライト

shikiは初回のコードブロック描画時にdynamic importで読み込まれます。SSRとハイドレーションエラーを回避する目的で、onMounted発火後にハイライトされます。ライト・ダーク両テーマの色をCSS変数で出力するため、colorScheme: "auto"を明示した場合においてもOSの設定変更が反映されます。

AiScriptの構文定義はaiscript-vscode(MIT, v0.1.16)に準拠しています。

テーマ

テーマに関連する全ての処理はMisskeyと互換のため、テーマコードがそのまま利用可能です。

MisskeyのテーマデータはAGPL-3.0のため同梱していません。必要に応じて利用側で用意していい感じに指定してください。

provideMfmConfig({
  colorScheme: "auto",
  // Misskeyのpackages/frontend-shared/themes/_light.json5, _dark.json5
  baseThemes: [lightBaseCode, darkBaseCode],
  // テーマコード(JSON5文字列)またはオブジェクト
  lightTheme: miLightCode,
  darkTheme: myDarkThemeCode,
});

1. 文字列はJSON5として解析しており、id, name, baseを検証します
2. テーマのbaseと同じidのデフォルトテーマがあれば、その全項目の上にテーマのpropsを重ねる挙動をします
3. propsの各値を解決します。@参照, $定数, :darken<n<色 :lighten<n<色 :alpha<n<色 :hue<n<色 :saturate<n<色, "で開始される値に対応しています。
4. id: "light"のデフォルトテーマがあれば、その項目からX始まりを除いたもの(MisskeyのthemeProps)に含まれる項目のみを出力します(デフォルトテーマが存在しない場合は、解決した全項目を出力します)
5. 各項目を--mfm-theme-<項目名>のCSS変数としてルート要素とポップアップに出力します(Misskeyの--MI_THEME-<項目名>に相当)。Misskeyのhtml要素と同じく、color: var(--mfm-theme-fg)と、baseに応じたcolor-schemeを設定します
6. コードハイライトのテーマは、デフォルトテーマのcodeHighlighterと合成します。base: "_none_"はoverridesをそのままshikiのテーマとし、それ以外は同梱テーマへoverridesをdeepMergeします。(codeHighlighterがない場合はdark-plusです)

colorScheme: "auto"は、Misskeyの「デバイスのダークモードと同期」に相当します。 利用側の文字色を継承したい場合は、テーマでfg: '"inherit'を指定してください。

本家(Misskey 2026.10.系, Mi Light)のhtml要素に設定された62項目の--MI_THEME-*と、同バージョンのテーマファイルから本ライブラリが出力した--mfm-theme-*が全項目一致することを確認しています。

ユーザプレビュー

createUserPreviewFetcher(endpoint)は、MisskeyのPOST /api/users/showの応答を変換する取得関数を作成ます。フォロー数・フォロワー数は、公開範囲がpublicの場合のみ表示され、名前と自己紹介はMFMとして解釈・描画されます。フォロー等、一切の操作を含みません。

provideMfmConfig({
  userPreview: createUserPreviewFetcher("https://misskey.example/api/users/show"),
});

独自実装のコンポーネントから設定を参照する場合はuseMfmContext()が利用可能です。

URLプレビュー

取得処理はurlPreviewに指定した関数で行います。createUrlPreviewFetcher(endpoint, { lang })は、Misskeyの/urlエンドポイント(summaly)互換の応答を変換する取得関数を作成します。(一般に、)Misskeyの/urlはCORSヘッダをレスポンスに含めないため、ブラウザから別オリジンのサーバを直接参照することはできません。同一オリジンで動かすかいい感じのサーバで中継してください(デモの開発サーバは中継しています)

provideMfmConfig({
  urlPreview: createUrlPreviewFetcher("/api/url-preview", { lang: "ja-JP" }),
});

サイト内遷移

const router = useRouter();
provideMfmConfig({
  instanceUrl: "https://misskey.example",
  navigate: (path) => router.push(path),
  paths: { user: (acct) => `/users/${acct}` },
});

リンクのhrefは常に実際のURLです

設定の共有(provideMfmConfig)

親コンポーネントのsetupで実行すると、子孫の<Mfm>へ設定が共有されます。refやgetterを指定するとリアクティブに反映されます。入れ子で実行した場合は親の設定とマージされ、<Mfm>のpropsが最優先です。

import { provideMfmConfig, createInstanceEmojiResolver } from "mfm-vue";

provideMfmConfig(() => ({
  instanceUrl: "https://misskey.example",
  customEmojis: createInstanceEmojiResolver("https://misskey.example"),
  animated: !prefersReducedMotion.value,
}));

app.provide(mfmConfigKey, () => config)で全体へ適用することも可能です。

描画の差し替え

コンポーネントで差し替える際には、componentsにpropsの一部だけを宣言したコンポーネントを指定することができます。

<script setup lang="ts">
import { Mfm } from "mfm-vue";
import RouterMention from "./RouterMention.vue"; // props: MfmMentionProps
import ShikiCode from "./ShikiCode.vue"; // props: MfmBlockCodeProps
</script>

<template>
  <Mfm :text="text" :components="{ mention: RouterMention, blockCode: ShikiCode }" />
</template>

子要素のない構文は、slotでも差し替え可能です。

<Mfm :text="text">
  <template #hashtag="{ hashtag, href }">
    <RouterLink :to="href">#{{ hashtag }}</RouterLink>
  </template>
  <template #unicodeEmoji="{ emoji }">
    <TwemojiImage :emoji="emoji" />
  </template>
</Mfm>

メンションとカスタム絵文字のhostは確定済みのホスト名である必要があります。instanceUrlを明示した場合、取得元サーバ所属の場合も実際のホスト名が参照され、isSourceHostがtrueになります。

関数構文の拡張

import { h } from "vue";
import type { MfmFnHandler } from "mfm-vue";

const highlight: MfmFnHandler = (ctx) =>
  h("mark", { class: "my-highlight" }, ctx.renderChildren());

// <Mfm :fns="{ highlight, blur: false }" />

ハンドラの戻り値がnullの場合は、未知の関数として$[name ...]のまま表示します。ctxにはargs, scale, renderChildren(scale?), renderNodes(nodes), transformText(text), renderComponent(name, props), emitClick(ev)があります。

外部データの取得

本ライブラリに外部APIへのアクセス処理はありません。絵文字一覧などは利用側で取得し、オプションに指定する必要があります。

const emojis = shallowRef<Record<string, string>>({});
const res = await fetch("https://misskey.example/api/emojis");
const json = await res.json();
emojis.value = Object.fromEntries(json.emojis.map((e) => [e.name, e.url]));

provideMfmConfig(() => ({ customEmojis: emojis.value }));

絵文字URLの解決順序

1. emojiUrls[name]
2. 投稿者がリモートかつemojiUrlsが指定されている場合、:name:の文字列表示
3. customEmojisが関数の場合customEmojis(name, host)(hostは取得元サーバの絵文字であればnull)
4. customEmojisがオブジェクトの場合、取得元サーバの絵文字に限りcustomEmojis[name]
5. いずれもなければurl: null(既定コンポーネントではテキスト表示)

SSR

renderToStringで描画できます。DOM APIに依存する処理(sparkleのパーティクル, unixtimeのローカル時刻表示)はonMounted以降に実行します。また、ハイドレーション時の不一致防止のため、unixtimeはonMounted発火までUTC表記で出力します。

スタイル

スタイルはコンポーネント単位のscoped CSSです。$[...]などのASTから生成される要素は、<Mfm>の描画中に生成するため<Mfm>のscope属性が付与されます。アニメーションはクラスで指定し、speed, delay引数はインラインのanimation-duration, animation-delayで上書きしています。

描画関数からの利用

renderMfmNodesはASTをVNodeの配列へ変換します。<Mfm>の外で実行した場合、書式や$[...]用のscoped CSSは適用されません。

import { renderMfmNodes, resolveMfmOptions } from "mfm-vue";
import * as mfm from "mfm-js";

const children = renderMfmNodes(mfm.parse(text), {
  options: resolveMfmOptions({ instanceUrl: "https://misskey.example" }),
  plain: false,
  nowrap: false,
  slots: {},
  emitClick: () => {},
});

対応状況

対応表

mfm.js 0.27.0の全構文と、Misskey本家が描画する全関数(24種類)に対応しています。

構文

関数: 色・スタイル

関数: 変形

関数: アニメーション

関数: その他

設定

パフォーマンス

• 構文解析はtext, plain, nestLimitの変更時のみ実行します。解析済みのASTをnodesで渡すことで解析を省略できます
• テーマの解決結果は、同じ入力の<Mfm>間で共有します(最大32件)
• shiki, 言語定義, コードハイライトのテーマ, Unicode絵文字の名前一覧は、使用時にdynamic importで読み込まれます
• unixtimeの相対時刻は、すべての<Mfm>で1つのタイマー(10秒間隔)を共有し、ページの非表示中は更新しません

計測条件はApple M4 Max(RAM 128Gi), Node.js 24.21.0です。平均161文字のノート(メンション, ハッシュタグ, URL, 絵文字, 装飾, $[...]を含む)を使用し、値は中央値です。

dist/index.jsは80.5KiB(gzip 21.9KiB), dist/style.cssは20.0KiB(gzip 4.1KiB)です。依存パッケージを含みません。

開発

git submodule update --init   # AiScriptの構文定義
pnpm install
pnpm dev        # 開発サーバ(http://localhost:5173)
pnpm test       # Vitest
pnpm typecheck  # vue-tsc
pnpm lint       # ESLint
pnpm build      # dist/ へライブラリを出力
pnpm build:demo # demo/dist/ へデモを出力
pnpm compare <ノートのURL> # Misskeyのノートページとの描画比較(Headless Chrome)

ディレクトリ構成

src/
  components/
    Mfm.vue                <Mfm>(props, 設定のマージ, 解析, ルート要素)
    defaults/*.vue         差し替え可能な既定の描画部品
  render/
    index.ts               ノード種別から変換関数を選択
    nodes/text.ts          text, plain
    nodes/format.ts        bold, strike, italic, small, center, quote
    nodes/link.ts          url, link, mention, hashtag
    nodes/emoji.ts         emojiCode, unicodeEmoji
    nodes/code.ts          inlineCode, blockCode, mathInline, mathBlock
    nodes/search.ts        search
    nodes/fn.ts            $[...]のハンドラの実行
    component.ts           slot, components設定の解決
    host.ts                ホストの確定
  fns/
    animation.ts           tada, jelly, twitch, shake, spin, jump, bounce, rainbow, sparkle
    transform.ts           flip, x2, x3, x4, rotate, position, scale
    style.ts               font, blur, fg, bg, border
    special.ts             ruby, unixtime, clickable
  styles/
    format.css             ルート要素, 書式
    fn.css                 $[...]の装飾, 変形
    animation.css          アニメーション, キーフレーム
  config.ts                provideMfmConfig, オプションの解決
  context.ts               <Mfm>から描画部品への設定共有
  highlight.ts             shikiによるトークン化
  i18n/                    同梱文言, 相対時刻の整形
  clock.ts                 相対時刻用の共有時計
  preview.ts               URLプレビューの取得, ホバー判定
  navigation.ts            サイト内遷移の判定
  media.ts                 メディアプロキシのURL規則
  theme.ts                 Misskey本家と同じ手順のテーマの解決
  theme-attrs.ts           テーマのCSS変数の出力
  emoji-name.ts            Unicode絵文字の名前
  emoji.ts                 絵文字URL生成関数
  utils.ts                 引数検証, nyaize
  types/                   公開型
    components.ts          描画部品のprops, slot
    fn.ts                  $[...]ハンドラ
    i18n.ts                文言
    options.ts             オプション
    preview.ts             URL, ユーザプレビュー
    theme.ts               テーマ
vendor/aiscript-vscode/    AiScriptの構文定義(git submodule)
demo/                      動作確認用デモ。MisskeyのテーマはGitHubから実行時に取得
scripts/                   distの読み込み検査, Misskeyとの描画比較
test/
  syntax/                  構文ごとのテスト
  fns/                     $[...]関数のテスト
  popup/                   URL, ユーザプレビューのテスト
  helpers.ts               描画用の補助関数

ライセンス

MIT