@izumisy/vitepress-plugin-react-preview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IzumiSy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @izumisy/vitepress-plugin-react-preview
+
+VitePress plugin for rendering live React component previews inside your VitePress documentation site.
+
+Transforms `` ```tsx preview `` fenced blocks in Markdown into interactive previews rendered via iframes, with full style isolation and dark mode support.
+
+## Features
+
+- **markdown-it plugin** — rewrites `` ```tsx preview `` blocks into `<PreviewBlock>` Vue components at the Markdown parsing stage
+- **Vite plugin** — serves preview modules and standalone preview pages using `@izumisy/vite-plugin-react-preview` under the hood
+- **Style isolation** — inline previews render inside iframes; standalone previews run in a separate page
+- **Dark mode** — syncs with VitePress theme toggle via `postMessage`
+- **Build support** — emits standalone HTML pages (`/__preview/{blockId}.html`) during `vitepress build`
+
+## Install
+
+```bash
+pnpm add -D @izumisy/vitepress-plugin-react-preview
+```
+
+## Setup
+
+In your VitePress config (`.vitepress/config.ts`):
+
+```ts
+import { defineConfig } from "vitepress";
+import { createMrpPlugin } from "@izumisy/vitepress-plugin-react-preview";
+
+const mrp = createMrpPlugin({
+  css: "@my-lib/styles", // optional: CSS to inject into previews
+});
+
+export default defineConfig({
+  markdown: {
+    config(md) {
+      md.use(mrp.markdownIt);
+    },
+  },
+  vite: {
+    plugins: [mrp.vite()],
+  },
+});
+```
+
+Then use `<PreviewBlock>` in your theme if needed:
+
+```vue
+<script setup>
+import PreviewBlock from "@izumisy/vitepress-plugin-react-preview/PreviewBlock.vue";
+</script>
+```
+
+## Preview Syntax
+
+Works with the same `` ```tsx preview `` syntax as `@izumisy/md-react-preview`:
+
+````md
+```tsx preview
+import { Button } from "@my-lib"
+
+<Button>Click me</Button>
+```
+
+```tsx preview standalone
+import { Sheet } from "@my-lib"
+
+<Sheet.Root>...</Sheet.Root>
+```
+````
+
+- **inline** (default) — rendered within the page via iframe
+- **standalone** — shows a code block with a link to a full-viewport preview page
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import { PreviewBlockEntry } from "@izumisy/vite-plugin-react-preview";
+import * as markdown_it0 from "markdown-it";
+import { Plugin } from "vite";
+
+//#region src/index.d.ts
+type MrpVitePressOptions = {
+  /** CSS file to inject into preview blocks (e.g. your component library's stylesheet) */css?: string;
+};
+/**
+ * Recursively find all .md files under a directory.
+ * @internal Exported for testing.
+ */
+declare function findMarkdownFiles(dir: string): string[];
+/**
+ * Pre-scan markdown files to populate the block registry before Rollup
+ * resolves the registry virtual module.
+ * @internal Exported for testing.
+ */
+declare function scanMarkdownBlocks(root: string, blockRegistry: Map<string, PreviewBlockEntry>): void;
+/**
+ * Create a md-react-preview plugin instance for VitePress.
+ *
+ * Returns an object with:
+ * - `markdownIt`: markdown-it plugin that transforms ` ```tsx preview ` fences
+ * - `vite()`: Vite plugins that serve preview blocks with live React components
+ */
+declare function createMrpPlugin(options?: MrpVitePressOptions): {
+  /**
+   * markdown-it plugin that transforms ` ```tsx preview ` fences into
+   * `<PreviewBlock>` Vue components and registers blocks in the shared registry.
+   */
+  markdownIt: (md: markdown_it0.default) => void;
+  /**
+   * Vite plugins that provide virtual modules for preview blocks.
+   */
+  vite(): Plugin[];
+};
+//#endregion
+export { MrpVitePressOptions, createMrpPlugin, findMarkdownFiles, scanMarkdownBlocks };

package/dist/index.mjs

@@ -0,0 +1,108 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createBasePreviewPlugin, createPreviewBuildPlugin, parseMeta, simpleHash } from "@izumisy/vite-plugin-react-preview";
+//#region src/markdown-it-plugin.ts
+/**
+* Create a markdown-it plugin that transforms ` ```tsx preview ` fenced code blocks
+* into a `<PreviewBlock>` Vue component with the code passed as props.
+*
+* Blocks are registered in the shared registry so the preview Vite plugin
+* can serve the preview pages.
+*
+* The code is base64-encoded to avoid escaping issues in HTML attributes.
+*/
+function createMarkdownItPlugin(blockRegistry) {
+	return function markdownItPreviewPlugin(md) {
+		const defaultFence = md.renderer.rules.fence;
+		md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+			const token = tokens[idx];
+			const info = token.info.trim();
+			if (info.startsWith("tsx preview")) {
+				const code = token.content.replace(/\n$/, "");
+				const encodedCode = Buffer.from(code).toString("base64");
+				const blockId = simpleHash(`${env.relativePath || "unknown"}:${token.map?.[0] ?? 0}`);
+				const meta = parseMeta(info.slice(11));
+				const isStandalone = meta.standalone === "true";
+				blockRegistry.set(blockId, {
+					code,
+					sourceFile: "",
+					wrap: meta.wrap,
+					height: meta.height,
+					standalone: isStandalone
+				});
+				const highlighted = md.options.highlight?.(code, "tsx", "") ?? "";
+				return `<PreviewBlock code="${encodedCode}" block-id="${blockId}" highlighted="${Buffer.from(highlighted).toString("base64")}"${meta.height ? ` height="${meta.height}"` : ""}${meta.wrap ? ` wrap="${meta.wrap}"` : ""}${meta.align ? ` align="${meta.align}"` : ""}${isStandalone ? ` standalone="true"` : ""} />\n`;
+			}
+			return defaultFence(tokens, idx, options, env, self);
+		};
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Recursively find all .md files under a directory.
+* @internal Exported for testing.
+*/
+function findMarkdownFiles(dir) {
+	const results = [];
+	for (const entry of readdirSync(dir)) {
+		if (entry.startsWith(".") || entry === "node_modules") continue;
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory()) results.push(...findMarkdownFiles(full));
+		else if (full.endsWith(".md")) results.push(full);
+	}
+	return results;
+}
+/**
+* Pre-scan markdown files to populate the block registry before Rollup
+* resolves the registry virtual module.
+* @internal Exported for testing.
+*/
+function scanMarkdownBlocks(root, blockRegistry) {
+	const mdFiles = findMarkdownFiles(root);
+	for (const file of mdFiles) {
+		const content = readFileSync(file, "utf-8");
+		const relativePath = relative(root, file);
+		const fenceRe = /^(`{3,})\s*(\S.*?)?\n([\s\S]*?)^\1\s*$/gm;
+		let m;
+		while ((m = fenceRe.exec(content)) !== null) {
+			const info = (m[2] || "").trim();
+			if (info.startsWith("tsx preview")) {
+				const code = m[3].replace(/\n$/, "");
+				const blockId = simpleHash(`${relativePath}:${content.slice(0, m.index).split("\n").length - 1}`);
+				const meta = parseMeta(info.slice(11));
+				blockRegistry.set(blockId, {
+					code,
+					sourceFile: "",
+					wrap: meta.wrap,
+					height: meta.height,
+					standalone: meta.standalone === "true"
+				});
+			}
+		}
+	}
+}
+/**
+* Create a md-react-preview plugin instance for VitePress.
+*
+* Returns an object with:
+* - `markdownIt`: markdown-it plugin that transforms ` ```tsx preview ` fences
+* - `vite()`: Vite plugins that serve preview blocks with live React components
+*/
+function createMrpPlugin(options = {}) {
+	const blockRegistry = /* @__PURE__ */ new Map();
+	return {
+		markdownIt: createMarkdownItPlugin(blockRegistry),
+		vite() {
+			return [...createBasePreviewPlugin("mrp-vitepress-preview", {
+				blockRegistry,
+				cssImport: options.css
+			}), createPreviewBuildPlugin({
+				blockRegistry,
+				scanBlocks: (root) => scanMarkdownBlocks(root, blockRegistry)
+			})];
+		}
+	};
+}
+//#endregion
+export { createMrpPlugin, findMarkdownFiles, scanMarkdownBlocks };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@izumisy/vitepress-plugin-react-preview",
+  "version": "0.1.0",
+  "description": "VitePress plugin for rendering React component previews via iframe",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./PreviewBlock.vue": "./src/PreviewBlock.vue"
+  },
+  "files": [
+    "dist/**",
+    "src/PreviewBlock.vue"
+  ],
+  "dependencies": {
+    "@izumisy/vite-plugin-react-preview": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22",
+    "markdown-it": "^14.1.0",
+    "tsdown": "^0.21.3",
+    "typescript": "~5.9.3",
+    "vite": "^6.3.5",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "markdown-it": ">=14",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "vite": ">=6",
+    "vue": ">=3"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "type-check": "tsc --incremental",
+    "test": "vitest run"
+  }
+}

package/src/PreviewBlock.vue

@@ -0,0 +1,281 @@
+<script setup lang="ts">
+import { ref, computed, onMounted, onBeforeUnmount } from "vue";
+
+const props = defineProps<{
+  code: string;
+  blockId: string;
+  highlighted?: string;
+  height?: string;
+  wrap?: string;
+  align?: string;
+  standalone?: string;
+}>();
+
+const isStandalone = computed(() => props.standalone === "true");
+const showCode = ref(true);
+const iframeRef = ref<HTMLIFrameElement | null>(null);
+const iframeHeight = ref(props.height ? Number(props.height) : 150);
+
+const decodedCode = computed(() => {
+  try {
+    return atob(props.code);
+  } catch {
+    return props.code;
+  }
+});
+
+const decodedHighlighted = computed(() => {
+  if (!props.highlighted) return "";
+  try {
+    return atob(props.highlighted);
+  } catch {
+    return "";
+  }
+});
+
+const currentTheme = ref(
+  typeof document !== "undefined" && document.documentElement.classList.contains("dark")
+    ? "dark"
+    : "light"
+);
+
+const previewUrl = computed(() => {
+  const params = new URLSearchParams({ theme: currentTheme.value });
+  if (props.wrap) params.set("wrap", props.wrap);
+  if (props.align) params.set("align", props.align);
+  return `/__preview/${props.blockId}?${params}`;
+});
+
+let themeObserver: MutationObserver | null = null;
+
+function syncThemeToIframe() {
+  const iframe = iframeRef.value;
+  if (iframe?.contentWindow) {
+    iframe.contentWindow.postMessage(
+      { type: "mrp-theme", theme: currentTheme.value },
+      "*"
+    );
+  }
+}
+
+function onMessage(e: MessageEvent) {
+  if (
+    e.data?.type === "mrp-resize" &&
+    e.data?.blockId === props.blockId
+  ) {
+    iframeHeight.value = e.data.height;
+  }
+}
+
+onMounted(() => {
+  window.addEventListener("message", onMessage);
+
+  themeObserver = new MutationObserver(() => {
+    const isDark = document.documentElement.classList.contains("dark");
+    const newTheme = isDark ? "dark" : "light";
+    if (currentTheme.value !== newTheme) {
+      currentTheme.value = newTheme;
+      syncThemeToIframe();
+    }
+  });
+  themeObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+});
+
+onBeforeUnmount(() => {
+  window.removeEventListener("message", onMessage);
+  themeObserver?.disconnect();
+});
+</script>
+
+<template>
+  <div class="mrp-preview vp-raw">
+    <template v-if="isStandalone">
+      <a
+        :href="previewUrl"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="mrp-preview-standalone-link"
+      >
+        <svg width="20" height="20" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" style="opacity:0.5">
+          <path d="M7 3H3v10h10V9" />
+          <path d="M10 2h4v4" />
+          <path d="M14 2L7 9" />
+        </svg>
+        <span class="mrp-preview-standalone-text">
+          <span class="mrp-preview-standalone-title">Open full-page preview</span>
+          <span class="mrp-preview-standalone-desc">This component requires a full viewport to render correctly.</span>
+        </span>
+      </a>
+    </template>
+    <template v-else>
+      <div class="mrp-preview-render">
+        <iframe
+          ref="iframeRef"
+          :src="previewUrl"
+          :style="{ height: iframeHeight + 'px' }"
+          class="mrp-preview-iframe"
+        />
+      </div>
+      <div class="mrp-preview-actions">
+        <a
+          :href="previewUrl"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="mrp-preview-fullscreen-link"
+        >
+          Open full preview
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M7 3H3v10h10V9" />
+            <path d="M10 2h4v4" />
+            <path d="M14 2L7 9" />
+          </svg>
+        </a>
+      </div>
+    </template>
+    <div class="mrp-preview-code">
+      <button
+        class="mrp-preview-toggle"
+        @click="showCode = !showCode"
+      >
+        <svg
+          width="16"
+          height="16"
+          viewBox="0 0 16 16"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          :class="{ 'mrp-chevron-open': showCode }"
+        >
+          <path d="M6 4l4 4-4 4" />
+        </svg>
+        Code
+      </button>
+      <div v-if="showCode && decodedHighlighted" v-html="decodedHighlighted" />
+      <div v-else-if="showCode" class="language-tsx vp-adaptive-theme">
+        <pre><code>{{ decodedCode }}</code></pre>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.mrp-preview {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  overflow: hidden;
+  margin: 16px 0;
+}
+
+.mrp-preview-render {
+  background-color: var(--vp-c-bg);
+}
+
+.mrp-preview-iframe {
+  display: block;
+  width: 100%;
+  border: none;
+  transition: height 0.15s ease;
+}
+
+.mrp-preview-code {
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.mrp-preview-toggle {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  width: 100%;
+  padding: 8px 12px;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: 13px;
+  color: var(--vp-c-text-2);
+  font-family: inherit;
+}
+
+.mrp-preview-toggle:hover {
+  color: var(--vp-c-text-1);
+}
+
+.mrp-chevron-open {
+  transform: rotate(90deg);
+}
+
+.mrp-preview-actions {
+  display: flex;
+  justify-content: flex-end;
+  padding: 6px 12px;
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.mrp-preview-fullscreen-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+  text-decoration: none;
+}
+
+.mrp-preview-fullscreen-link:hover {
+  color: var(--vp-c-text-1);
+}
+
+.mrp-preview-code svg {
+  transition: transform 0.15s;
+}
+
+.mrp-preview-code pre {
+  margin: 0 !important;
+  border-radius: 0 !important;
+}
+
+.mrp-preview-code :deep(pre) {
+  margin: 0 !important;
+  border-radius: 0 !important;
+  padding: 16px !important;
+}
+
+.mrp-preview-code :deep(pre code) {
+  font-size: 13px !important;
+  line-height: 1.6 !important;
+}
+
+.mrp-preview-standalone-link {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 20px 16px;
+  text-decoration: none;
+  color: var(--vp-c-text-2);
+  transition: background-color 0.15s;
+}
+
+.mrp-preview-standalone-link:hover {
+  background-color: var(--vp-c-bg-soft);
+}
+
+.mrp-preview-standalone-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.mrp-preview-standalone-title {
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--vp-c-text-1);
+}
+
+.mrp-preview-standalone-desc {
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+}
+</style>