hexo-renderer-mdx 1.0.4 → 1.1.1

package/README.md

@@ -8,8 +8,9 @@ A [Hexo](https://hexo.io/) renderer plugin for [MDX](https://mdxjs.com/) - Markd
 - ⚛️ React component integration
 - 📝 Markdown compatibility
 - 🎨 Custom component support
-- � ES6 import statements for external packages
-- �� Fast compilation with @mdx-js/mdx
+- 📁 ES6 import statements for external packages
+- ⚡ Fast compilation with @mdx-js/mdx
+- 🔄 Automatic hydration bundle rebuilds on `hexo generate` and when components change during `hexo server`
 
 ## Installation
 
@@ -211,6 +212,14 @@ hexo deploy
 
 The MDX files are compiled to static HTML - no JavaScript runtime needed on your site!
 
+#### Client-side hydration bundles (auto-built)
+
+If your MDX imports local React components, the renderer will emit a hydration entry in `public/.hexo-mdx-entry/` and automatically bundle it to `public/assets/mdx-hydrate-*.js`.
+
+- `hexo generate` runs bundling automatically after generation; no manual esbuild step is required.
+- During `hexo server`, component edits trigger targeted regeneration and bundling so the client asset stays fresh.
+- Avoid keeping old `mdx-hydrate-*.js` files in `source/assets/`; Hexo would copy them into `public/assets` and overwrite the freshly bundled output.
+
 ## Usage
 
 After installation, you can create `.mdx` files in your `source/_posts` or `source` directory.

package/index.js

@@ -5,6 +5,7 @@ const React = require('react');
 const fs = require('fs');
 const { createRequire } = require('module');
 const { pathToFileURL, fileURLToPath } = require('url');
+const crypto = require('crypto');
 
 let babelRegistered = false;
 function ensureBabelRegister(filePath) {
@@ -88,12 +89,20 @@ async function loadCompile() {
 async function mdxRenderer(data) {
   const { text, path: filePath } = data;
   
+  // Initialize dependencies Set for tracking imported component files
+  if (!data.dependencies) {
+    data.dependencies = new Set();
+  }
+  
   try {
     // Ensure Babel can handle JSX/TS imports from MDX files (e.g., local components).
     ensureBabelRegister(filePath);
 
     // Ensure compile function is loaded
     await loadCompile();
+
+    // Stable per-file hash to namespace hydration ids and bundles
+    const fileHash = crypto.createHash('md5').update(filePath).digest('hex').slice(0, 8);
     
     // Read the original file directly to bypass Hexo's template processing
     let content;
@@ -142,30 +151,43 @@ async function mdxRenderer(data) {
       // For primitive or function values, just set as default
       return { default: mod };
     };
+    // Collect components used so we can hydrate them client-side
+    const componentsForHydration = [];
     const dynamicImport = (specifier) => {
       const asString = String(specifier);
       const req = createRequire(filePath);
-      // Check if it's already a file:// URL string
-      if (asString.startsWith('file://')) {
-        try {
-          const fsPath = fileURLToPath(asString);
-          return Promise.resolve(toModuleNamespace(req(fsPath)));
-        } catch (err) {
-          // Re-throw with better error message
-          throw new Error(`Failed to require file:// URL: ${err.message}`);
-        }
-      }
+
+      // Resolve a filesystem path for this specifier
+      let fsPath;
       try {
-        // Try to construct a URL to see if it's relative
-        const resolvedUrl = new URL(asString, pathToFileURL(filePath));
-        if (resolvedUrl.protocol === 'file:') {
-          return Promise.resolve(toModuleNamespace(req(fileURLToPath(resolvedUrl))));
+        if (asString.startsWith('file://')) {
+          fsPath = fileURLToPath(asString);
+        } else {
+          const resolvedUrl = new URL(asString, pathToFileURL(filePath));
+          if (resolvedUrl.protocol === 'file:') {
+            fsPath = fileURLToPath(resolvedUrl);
+          }
         }
-        return Promise.resolve(toModuleNamespace(req(asString)));
-      } catch (urlErr) {
-        // If URL construction failed, try bare require
-        return Promise.resolve(toModuleNamespace(req(asString)));
+      } catch (e) {
+        // ignore - will try bare require
       }
+
+      // Create a placeholder component for server-side rendering
+      const placeholderId = `mdx-cmp-${fileHash}-${componentsForHydration.length + 1}`;
+      const Placeholder = (props) => {
+        return React.createElement('div', { 'data-mdx-component': placeholderId });
+      };
+
+      // Record mapping for hydration bundle (use filesystem path when available, otherwise the original specifier)
+      componentsForHydration.push({ id: placeholderId, spec: fsPath || asString });
+
+      // Register component file as a dependency so Hexo watches it for changes
+      if (fsPath && data.dependencies) {
+        data.dependencies.add(fsPath);
+      }
+
+      // Return an ES-like namespace with default export set to placeholder
+      return Promise.resolve({ default: Placeholder });
     };
 
     // Swap all occurrences of 'import(' (awaited or not) with our shim to avoid vm dynamic import callbacks.
@@ -180,8 +202,67 @@ async function mdxRenderer(data) {
     const html = renderToString(
       React.createElement(MDXContent, {})
     );
+
+    // If there are components to hydrate, generate a client bundle using esbuild (if available)
+    let finalHtml = html;
+    if (componentsForHydration.length > 0) {
+      try {
+        const esbuild = require('esbuild');
+        const os = require('os');
+        const tmpdir = os.tmpdir();
+        const hash = fileHash;
+        const outName = `mdx-hydrate-${hash}.js`;
+        // Output compiled hydration bundle and temporary entry into the site's public directory
+        const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+        const publicDir = (hexo && hexo.public_dir) ? hexo.public_dir : require('path').join(projectRoot, 'public');
+        const outDir = require('path').join(publicDir, 'assets');
+        const entryPath = require('path').join(publicDir, '.hexo-mdx-entry', `mdx-entry-${hash}.mjs`);
+
+        const imports = componentsForHydration.map((c, i) => {
+          // Convert absolute path to relative path from entry directory
+          let importPath = c.spec;
+          if (require('path').isAbsolute(importPath)) {
+            importPath = require('path').relative(require('path').dirname(entryPath), importPath);
+          }
+          // Normalize slashes for JS import
+          importPath = importPath.replace(/\\/g, '/');
+          // Ensure relative imports start with ./ or ../
+          if (!importPath.startsWith('.')) {
+            importPath = './' + importPath;
+          }
+          return `import C${i} from ${JSON.stringify(importPath)};`;
+        }).join('\n');
+
+        const mapping = componentsForHydration.map((c, i) => `  '${c.id}': C${i}`).join(',\n');
+
+        const entrySource = `import React from 'react';\nimport { hydrateRoot } from 'react-dom/client';\n\n// Make React available globally for imported components\nwindow.React = React;\n\n${imports}\n\nconst mapping = {\n${mapping}\n};\n\nObject.keys(mapping).forEach(id => {\n  const Comp = mapping[id];\n  const el = document.querySelector('[data-mdx-component="'+id+'"]');\n  if (el) {\n    hydrateRoot(el, React.createElement(Comp, {}));\n  }\n});\n`;
+
+        require('fs').mkdirSync(require('path').dirname(entryPath), { recursive: true });
+        require('fs').writeFileSync(entryPath, entrySource, 'utf8');
+        require('fs').mkdirSync(outDir, { recursive: true });
+
+        esbuild.buildSync({
+          entryPoints: [entryPath],
+          bundle: true,
+          format: 'esm',
+          outfile: require('path').join(outDir, outName),
+          platform: 'browser',
+          jsx: 'transform',
+          jsxFactory: 'React.createElement',
+          jsxFragment: 'React.Fragment',
+          minify: false,
+          absWorkingDir: process.cwd(),
+          loader: { '.jsx': 'jsx', '.js': 'js', '.mjs': 'js' }
+        });
+
+        // Hydration bundle is placed under /assets in the public dir
+        finalHtml = `<div id="mdx-root-${hash}">${html}</div><script type="module" src="/assets/${outName}"></script>`;
+      } catch (err) {
+        console.error('MDX hydration bundle failed:', err.message);
+      }
+    }
     
-    return html;
+    return finalHtml;
   } catch (err) {
     // Provide more detailed error information
     const errorMsg = `MDX compilation failed for ${filePath}: ${err.message}`;
@@ -199,6 +280,414 @@ async function mdxRenderer(data) {
  * Register the MDX renderer with Hexo
  * Note: Using disableNunjucks: true to prevent template processing of {{ }} syntax
  */
-hexo.extend.renderer.register('mdx', 'html', mdxRenderer, {
+const path = require('path');
+const chokidar = require('chokidar');
+const componentDependencies = new Map(); // Map of component path -> Set of MDX files that import it
+
+// Bundle the entry file with esbuild to create the hydration client bundle
+function bundleEntryToPublic() {
+  try {
+    const esbuild = require('esbuild');
+    const crypto = require('crypto');
+    const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+    const publicDir = (hexo && hexo.public_dir) ? hexo.public_dir : path.join(projectRoot, 'public');
+    
+    // Clear require cache for components before bundling to ensure fresh imports
+    Object.keys(require.cache).forEach(key => {
+      if (key.includes('source/components') || key.includes('source\\components')) {
+        delete require.cache[key];
+      }
+    });
+    
+    // Find all entry files in public/.hexo-mdx-entry and bundle each one
+    const entryDir = path.join(publicDir, '.hexo-mdx-entry');
+    if (!fs.existsSync(entryDir)) {
+      return; // No entry generated, skip bundling
+    }
+    
+    // Get all entry files
+    let entryFiles = [];
+    try {
+      const files = fs.readdirSync(entryDir);
+      entryFiles = files.filter(f => f.startsWith('mdx-entry-') && f.endsWith('.mjs'));
+    } catch (e) {
+      return; // Error reading entry dir, skip
+    }
+    
+    if (entryFiles.length === 0) return;
+    
+    const outDir = path.join(publicDir, 'assets');
+    fs.mkdirSync(outDir, { recursive: true });
+    
+    // Bundle each entry file individually
+    entryFiles.forEach(entryFile => {
+      const entryPath = path.join(entryDir, entryFile);
+      const hash = entryFile.match(/mdx-entry-([a-f0-9]+)/)?.[1] || 'unknown';
+      const outName = `mdx-hydrate-${hash}.js`;
+      
+      try {
+        esbuild.buildSync({
+          entryPoints: [entryPath],
+          bundle: true,
+          format: 'iife',
+          outfile: path.join(outDir, outName),
+          platform: 'browser',
+          target: 'es2017',
+          minify: false,
+          absWorkingDir: process.cwd(),
+          loader: { '.jsx': 'jsx', '.js': 'js', '.mjs': 'js' }
+        });
+        console.log(`INFO  ✓ Bundled entry to ${path.join(outDir, outName)}`);
+      } catch (err) {
+        console.warn(`INFO  Bundle error for ${entryFile}: ${err.message}`);
+      }
+    });
+  } catch (err) {
+    // Silently skip if esbuild is unavailable
+  }
+}
+
+// Bundle a single entry by its MDX file hash (targets only one output)
+function bundleEntryByHash(hash) {
+  try {
+    const esbuild = require('esbuild');
+    const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+    const publicDir = (hexo && hexo.public_dir) ? hexo.public_dir : path.join(projectRoot, 'public');
+    const entryPath = path.join(publicDir, '.hexo-mdx-entry', `mdx-entry-${hash}.mjs`);
+    const outDir = path.join(publicDir, 'assets');
+    const outName = `mdx-hydrate-${hash}.js`;
+
+    if (!fs.existsSync(entryPath)) {
+      return; // No entry for this hash yet
+    }
+
+    fs.mkdirSync(outDir, { recursive: true });
+    esbuild.buildSync({
+      entryPoints: [entryPath],
+      bundle: true,
+      format: 'iife',
+      outfile: path.join(outDir, outName),
+      platform: 'browser',
+      target: 'es2017',
+      minify: false,
+      absWorkingDir: process.cwd(),
+      loader: { '.jsx': 'jsx', '.js': 'js', '.mjs': 'js' }
+    });
+    console.log(`INFO  ✓ Bundled entry to ${path.join(outDir, outName)}`);
+  } catch (err) {
+    console.warn(`INFO  Bundle error for hash ${hash}: ${err && err.message}`);
+  }
+}
+
+// Persist component -> [mdxFiles] mapping into the public dir so it ships with the site
+function saveComponentPathJson() {
+  try {
+    const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+    const publicDir = (hexo && hexo.public_dir) ? hexo.public_dir : path.join(projectRoot, 'public');
+    const publicOut = path.join(publicDir, 'hexo-renderer-mdx.component-path.json');
+    const obj = {};
+    componentDependencies.forEach((mdxSet, compPath) => {
+      try {
+        obj[compPath] = Array.from(mdxSet);
+      } catch (e) {
+        obj[compPath] = [];
+      }
+    });
+    fs.mkdirSync(publicDir, { recursive: true });
+    fs.writeFileSync(publicOut, JSON.stringify(obj, null, 2), 'utf8');
+  } catch (err) {
+    console.warn('Could not write component-path JSON:', err && err.message);
+  }
+}
+
+// Wrap renderer to track component dependencies
+const originalMdxRenderer = mdxRenderer;
+async function mdxRendererWithTracking(data) {
+  const result = await originalMdxRenderer(data);
+  
+  // Track which components this MDX file depends on
+  if (data.dependencies && data.dependencies.size > 0) {
+    data.dependencies.forEach(componentPath => {
+      if (!componentDependencies.has(componentPath)) {
+        componentDependencies.set(componentPath, new Set());
+      }
+      componentDependencies.get(componentPath).add(data.path);
+    });
+    // Persist mapping to JSON so it's available across runs and survives hexo clean
+    try {
+      saveComponentPathJson();
+    } catch (e) {
+      // ignore
+    }
+  }
+  
+  return result;
+}
+
+hexo.extend.renderer.register('mdx', 'html', mdxRendererWithTracking, {
   disableNunjucks: true
 });
+
+/**
+ * Watch component files and trigger full site regeneration when they change
+ */
+let mdxComponentWatcher = null;
+// Only register watcher in real Hexo server runs
+if (
+  hexo &&
+  hexo.extend &&
+  hexo.extend.filter &&
+  typeof hexo.extend.filter.register === 'function' &&
+  hexo.env && hexo.env.cmd === 'server'
+) {
+hexo.extend.filter.register('after_init', function() {
+  // Set up file watcher for component paths from the JSON mapping
+  const sourceDir = path.join(hexo.source_dir, 'components');
+  const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+  const componentPathJsonPath = path.join(projectRoot, 'hexo-renderer-mdx.component-path.json');
+  
+  // Only initialize the persistent watcher during `hexo server` runs.
+  // For other commands (clean/generate), skip watcher to allow the process to exit.
+  if (!hexo || !hexo.env || hexo.env.cmd !== 'server') {
+    return;
+  }
+
+  // Function to read component paths from JSON and extract keys
+  function getComponentPathsFromJson() {
+    try {
+      if (fs.existsSync(componentPathJsonPath)) {
+        const mapping = JSON.parse(fs.readFileSync(componentPathJsonPath, 'utf8')) || {};
+        return Object.keys(mapping).filter(p => fs.existsSync(p));
+      }
+    } catch (e) {
+      // ignore parse/read errors
+    }
+    return [];
+  }
+
+  // Function to recreate the watcher with current component paths
+  function recreateWatcher() {
+    if (mdxComponentWatcher) {
+      mdxComponentWatcher.close();
+    }
+
+    const componentPaths = getComponentPathsFromJson();
+    
+    // Watch both the component files and the JSON mapping file itself
+    const pathsToWatch = [...componentPaths, componentPathJsonPath];
+    
+    if (pathsToWatch.length === 0) {
+      console.log(`INFO  No component paths to watch yet`);
+      return;
+    }
+
+    try {
+      mdxComponentWatcher = chokidar.watch(pathsToWatch, {
+        ignored: /node_modules|\.git/,
+        persistent: true
+      });
+      
+      console.log(`INFO  Watching ${componentPaths.length} component path(s)`);
+      
+      // Add event listeners for debugging
+      mdxComponentWatcher.on('ready', () => {
+        console.log('INFO  Watcher ready, monitoring for changes...');
+      });
+      
+      mdxComponentWatcher.on('error', (error) => {
+        console.error('INFO  Watcher error:', error);
+      });
+      
+      mdxComponentWatcher.on('all', (event, watchedPath) => {
+        if (event === 'change' || event === 'add' || event === 'unlink') {
+          console.log(`INFO  Watcher event: ${event} - ${watchedPath}`);
+          
+          // If the JSON mapping file was changed, update the watcher
+          if (watchedPath === componentPathJsonPath && (event === 'change' || event === 'add')) {
+            console.log(`INFO  Component mapping updated, refreshing watched paths...`);
+            process.nextTick(() => {
+              recreateWatcher();
+            });
+            return;
+          }
+        }
+      });
+    } catch (err) {
+      console.warn('Failed to create component watcher:', err.message);
+    }
+  }
+
+  try {
+    const handleComponentChange = (changedPath) => {
+      console.log(`\nINFO  ⚡ Component file changed: ${changedPath}`);
+      console.log(`INFO  Clearing caches and triggering regeneration...`);
+
+      // PAUSE the watcher to prevent it from detecting the file deletions during regeneration
+      try { mdxComponentWatcher.close(); } catch (e) {}
+
+      // Clear the require cache for all components and Babel
+      Object.keys(require.cache).forEach(key => {
+        if (key.includes('source/components') || key.includes('.hexo-mdx-entry') || key.includes('source\\components')) {
+          delete require.cache[key];
+        }
+      });
+
+      // Delete the compiled entry directory to force recreation
+      const fs = require('fs');
+      const mdxEntryDir = path.join(hexo.base_dir, '.hexo-mdx-entry');
+      if (fs.existsSync(mdxEntryDir)) {
+        try {
+          fs.rmSync(mdxEntryDir, { recursive: true });
+        } catch (err) {
+          // Ignore cleanup errors
+        }
+      }
+
+      // Invalidate Hexo's locals cache
+      if (hexo.locals) {
+        hexo.locals.invalidate();
+      }
+
+      // Read component-path JSON (prefer the copy in public) and try to rerender only affected MDX files
+      const mappingCandidates = [
+        path.join((hexo && hexo.public_dir) ? hexo.public_dir : path.join(hexo.base_dir || process.cwd(), 'public'), 'hexo-renderer-mdx.component-path.json'),
+        path.join(hexo.base_dir || process.cwd(), 'hexo-renderer-mdx.component-path.json')
+      ];
+      let mapping = null;
+      for (const mappingPath of mappingCandidates) {
+        try {
+          if (fs.existsSync(mappingPath)) {
+            mapping = JSON.parse(fs.readFileSync(mappingPath, 'utf8')) || null;
+            break;
+          }
+        } catch (e) {
+          mapping = null;
+        }
+      }
+
+      const normalize = p => path.resolve(p).split(path.sep).join(path.sep);
+      const normalizedChanged = normalize(changedPath);
+
+      let affectedMdxFiles = [];
+      if (mapping) {
+        Object.keys(mapping).forEach(compPath => {
+          const normalizedComp = normalize(compPath);
+          if (
+            normalizedChanged === normalizedComp ||
+            normalizedChanged.startsWith(normalizedComp + path.sep) ||
+            normalizedComp.startsWith(normalizedChanged + path.sep)
+          ) {
+            const arr = mapping[compPath] || [];
+            arr.forEach(m => { if (m && affectedMdxFiles.indexOf(m) === -1) affectedMdxFiles.push(m); });
+          }
+        });
+      }
+
+      // If we found affected files, try to rerender them individually; otherwise fallback to full clean + generate
+      process.nextTick(async () => {
+        if (affectedMdxFiles.length > 0) {
+          console.log(`INFO  Rerendering ${affectedMdxFiles.length} affected MDX file(s)...`);
+          let failed = false;
+          for (const mdxFile of affectedMdxFiles) {
+            try {
+              // Best-effort: try to call a targeted generate if available; fall back to full generate on failure
+              await hexo.call('generate', { watch: false, file: mdxFile }).catch(() => { throw new Error('per-file generate unsupported'); });
+            } catch (err) {
+              failed = true;
+              break;
+            }
+          }
+          if (!failed) {
+            console.log('INFO  ✓ Per-file regeneration complete');
+            // Bundle only the affected entries by their file hash
+            const hashes = Array.from(new Set(affectedMdxFiles.map(f => crypto.createHash('md5').update(f).digest('hex').slice(0, 8))));
+            hashes.forEach(h => bundleEntryByHash(h));
+            // Resume watcher
+            recreateWatcher();
+            return;
+          }
+          // Fallback to full clean+generate below
+        }
+
+        // Fallback: full clean + generate
+        hexo.call('clean').then(() => {
+          return hexo.call('generate', {watch: false});
+        }).then(() => {
+          console.log('INFO  ✓ Regeneration complete');
+          // Bundle only the affected entries (if any were identified)
+          if (affectedMdxFiles.length > 0) {
+            const hashes = Array.from(new Set(affectedMdxFiles.map(f => crypto.createHash('md5').update(f).digest('hex').slice(0, 8))));
+            hashes.forEach(h => bundleEntryByHash(h));
+          }
+          console.log('INFO  ✓ Refresh your browser to see changes');
+          // Resume watcher
+          recreateWatcher();
+        }).catch(err => {
+          console.warn('Regeneration error:', err.message);
+          // Resume watcher even on error
+          recreateWatcher();
+        });
+      });
+    };
+    
+    mdxComponentWatcher.on('change', handleComponentChange);
+    
+    console.log('INFO  Component file watcher initialized');
+  } catch (err) {
+    console.warn('Component file watcher setup warning:', err.message);
+  }
+
+  // Initialize the watcher for the first time
+  recreateWatcher();
+});
+}
+
+// Close watcher when Hexo exits to allow process to terminate properly
+if (hexo && typeof hexo.on === 'function') {
+  hexo.on('exit', function() {
+    if (mdxComponentWatcher) {
+      mdxComponentWatcher.close();
+    }
+  });
+}
+
+// Ensure component-path JSON is placed into public when site is generated,
+// and bundle the entry if one was created during rendering.
+try {
+  if (
+    hexo &&
+    hexo.extend &&
+    hexo.extend.filter &&
+    typeof hexo.extend.filter.register === 'function'
+  ) {
+    hexo.extend.filter.register('after_generate', function() {
+      try {
+        const projectRoot = hexo && hexo.base_dir ? hexo.base_dir : process.cwd();
+        const src = path.join(projectRoot, 'hexo-renderer-mdx.component-path.json');
+        const publicDir = (hexo && hexo.public_dir) ? hexo.public_dir : path.join(projectRoot, 'public');
+        const dest = path.join(publicDir, 'hexo-renderer-mdx.component-path.json');
+        if (fs.existsSync(src)) {
+          fs.mkdirSync(publicDir, { recursive: true });
+          fs.copyFileSync(src, dest);
+        }
+        
+        // Bundle the entry file to produce the hydration client bundle
+        bundleEntryToPublic();
+      } catch (e) {
+        // ignore
+      }
+    });
+  }
+} catch (e) {
+  // ignore if filter registration not available
+}
+
+// Export renderer functions for tests and direct usage outside Hexo
+try {
+  module.exports = {
+    mdxRenderer,
+    mdxRendererWithTracking
+  };
+} catch (e) {
+  // ignore export errors in unusual runtimes
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexo-renderer-mdx",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "MDX renderer plugin for Hexo with React component support",
   "main": "index.js",
   "scripts": {
@@ -25,13 +25,14 @@
   },
   "homepage": "https://github.com/Bryan0324/hexo-renderer-mdx#readme",
   "dependencies": {
-    "@babel/register": "^7.25.0",
     "@babel/core": "^7.25.0",
     "@babel/plugin-syntax-dynamic-import": "^7.8.3",
     "@babel/plugin-syntax-jsx": "^7.25.0",
     "@babel/plugin-transform-react-jsx": "^7.25.0",
+    "@babel/register": "^7.25.0",
     "@mdx-js/mdx": "^3.0.0",
-    "react": "^18.2.0",
+    "esbuild": "^0.27.2",
+    "react": "^18.3.1",
     "react-dom": "^18.2.0"
   },
   "peerDependencies": {