@ecopages/mdx 0.2.0-alpha.5 → 0.2.0-alpha.8

package/CHANGELOG.md

@@ -8,24 +8,26 @@ All notable changes to `@ecopages/mdx` are documented here.
 
 ### Features
 
-- **Decoupled from React** — The MDX integration now works as a standalone, runtime-agnostic integration. React dependencies have been removed; MDX routes are server-rendered without requiring the React integration (`4d5474a4`).
-- **Async MDX compilation** — The MDX loader plugin now compiles MDX files asynchronously, improving compatibility with async remark/rehype plugins (`9e879dbe`).
-- **Updated type definitions** — Plugin options are more precisely typed to clarify server-rendered MDX route configuration.
+- Made the MDX integration standalone so MDX routes can server-render without requiring the React integration.
+- Switched MDX compilation to the async pipeline for async remark and rehype plugin support.
+
+### Bug Fixes
+
+- Fixed configured `.md` extensions to compile as MDX instead of plain markdown so top-level `import` and `export` statements work when `.md` is opted in.
+- Fixed loader registration to respect configured extensions so standalone MDX no longer hijacks React `.mdx` pages during shared development and build flows.
+- Fixed native Node startup compatibility by using Node-safe `source-map` interop.
 
 ### Refactoring
 
-- Removed unused HMR strategy and renderer files that were React-specific.
-- README updated to document standalone MDX usage without React.
-- Ambient module declarations cleaned up (`5f46ecc5`).
-- Aligned with full orchestration mode (`fc07bdb0`).
+- Removed the React-specific renderer and HMR code from the package and aligned MDX with the unified orchestration pipeline.
 
 ### Documentation
 
-- README updated to clarify the integration is now usable without the React integration.
+- Updated the README for standalone MDX registration and the current integration setup.
 
 ---
 
 ## Migration Notes
 
-- If you were using `@ecopages/mdx` together with `@ecopages/react` for MDX routes, the two integrations must now be registered separately. MDX handles server rendering; React handles client hydration.
-- The `useReact` option and React-specific HMR hooks have been removed.
+- Register `@ecopages/mdx` and `@ecopages/react` separately when you want MDX server rendering together with React client hydration.
+- The previous React-specific MDX path, including `useReact` and the React-specific HMR hooks, has been removed.

package/README.md

@@ -1,8 +1,8 @@
-# Ecopages MDX Integration Plugin
+# @ecopages/mdx
 
-The `@ecopages/mdx` package adds standalone MDX support for non-React JSX runtimes such as `@kitajs/html`. It uses the MDX compiler through Ecopages' integration system and is intended for server-rendered `.mdx` routes.
+Integration plugin for standalone MDX support in Ecopages, specifically designed for non-React JSX runtimes (such as `@kitajs/html`). It configures the MDX compiler to process `.mdx` routes natively.
 
-## Install
+## Installation
 
 ```bash
 bunx jsr add @ecopages/mdx
@@ -10,10 +10,10 @@ bunx jsr add @ecopages/mdx
 
 ## Usage
 
-Integrating MDX into your Ecopages project is made simple. Import and apply the `mdxPlugin` in your Ecopages configuration as demonstrated below:
+Import and apply the `mdxPlugin` in your `eco.config.ts`:
 
 ```ts
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { mdxPlugin } from '@ecopages/mdx';
 
 const config = await new ConfigBuilder()
@@ -29,11 +29,12 @@ By default, the standalone plugin uses:
 - `jsxImportSource: '@kitajs/html'`
 - `jsxRuntime: 'automatic'`
 
-You can override MDX compiler options, but React runtimes are intentionally not supported here.
+> [!WARNING]
+> React runtimes are intentionally rejected by this standalone plugin.
 
-## Using MDX with React Router
+## Using MDX with React
 
-If you are using `@ecopages/react` with a client-side router, enable MDX directly within the React plugin instead of using this standalone plugin. This ensures unified routing, hydration, and HMR for both `.tsx` and `.mdx` pages:
+If you are using `@ecopages/react` and building a full React application, **do not** use this standalone MDX plugin. Instead, enable MDX directly within the React plugin configuration to ensure unified hydration, client-side routing, and HMR:
 
 ```ts
 import { reactPlugin } from '@ecopages/react';
@@ -44,9 +45,3 @@ reactPlugin({
 	mdx: { enabled: true },
 });
 ```
-
-See the `@ecopages/react` documentation for details.
-
-## React runtimes are not supported here
-
-Standalone `mdxPlugin()` rejects `jsxImportSource: 'react'` and related React JSX runtimes. For React-backed MDX, use [@ecopages/react](../react/README.md) with `mdx.enabled`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/mdx",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.8",
   "description": "MDX plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -37,7 +37,7 @@
     "directory": "packages/integrations/mdx"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.5",
+    "@ecopages/core": "0.2.0-alpha.8",
     "@kitajs/html": "^4.1.0",
     "@mdx-js/mdx": "^3.1.0"
   },

package/src/mdx-loader-plugin.js

@@ -1,8 +1,15 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { compile } from "@mdx-js/mdx";
-import { SourceMapGenerator } from "source-map";
+import sourceMap from "source-map";
 import { VFile } from "vfile";
+function resolveCompileFormat(filePath, compilerOptions) {
+  const configuredFormat = compilerOptions?.format;
+  if (configuredFormat && configuredFormat !== "detect") {
+    return configuredFormat;
+  }
+  return path.extname(filePath).toLowerCase() === ".md" ? "mdx" : configuredFormat;
+}
 function createMdxLoaderPlugin(compilerOptions) {
   const mdxExtensions = compilerOptions?.mdxExtensions ?? [".mdx"];
   const mdExtensions = compilerOptions?.mdExtensions ?? [".md"];
@@ -18,13 +25,14 @@ function createMdxLoaderPlugin(compilerOptions) {
         const file = new VFile({ path: filePath, value: source });
         const compiled = await compile(file, {
           ...compilerOptions,
-          SourceMapGenerator
+          format: resolveCompileFormat(filePath, compilerOptions),
+          SourceMapGenerator: sourceMap.SourceMapGenerator
         });
-        const sourceMap = compiled.map ? `
+        const inlineSourceMap = compiled.map ? `
 //# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString("base64")}
 ` : "";
         return {
-          contents: `${String(compiled.value)}${sourceMap}`,
+          contents: `${String(compiled.value)}${inlineSourceMap}`,
           loader: compilerOptions?.jsx ? "jsx" : "js",
           resolveDir: path.dirname(args.path)
         };

package/src/mdx-loader-plugin.ts

@@ -2,9 +2,31 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import { type CompileOptions, compile } from '@mdx-js/mdx';
-import { SourceMapGenerator } from 'source-map';
+import sourceMap from 'source-map';
 import { VFile } from 'vfile';
 
+/**
+ * Resolves the MDX parser mode for a source file.
+ *
+ * Files with a `.md` extension must be forced into `mdx` mode when the caller
+ * explicitly opts them into the MDX pipeline. Leaving the compiler in `detect`
+ * mode would treat `.md` files as plain markdown, causing top-level ESM such as
+ * `import` and `export` to render as text instead of being compiled.
+ *
+ * @param filePath Absolute or relative source file path.
+ * @param compilerOptions User-provided MDX compiler options.
+ * @returns The compile format that should be passed to `@mdx-js/mdx`.
+ */
+function resolveCompileFormat(filePath: string, compilerOptions?: CompileOptions): CompileOptions['format'] {
+	const configuredFormat = compilerOptions?.format;
+
+	if (configuredFormat && configuredFormat !== 'detect') {
+		return configuredFormat;
+	}
+
+	return path.extname(filePath).toLowerCase() === '.md' ? 'mdx' : configuredFormat;
+}
+
 export function createMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuildPlugin {
 	const mdxExtensions = compilerOptions?.mdxExtensions ?? ['.mdx'];
 	const mdExtensions = compilerOptions?.mdExtensions ?? ['.md'];
@@ -22,15 +44,16 @@ export function createMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuil
 
 				const compiled = await compile(file, {
 					...compilerOptions,
-					SourceMapGenerator,
+					format: resolveCompileFormat(filePath, compilerOptions),
+					SourceMapGenerator: sourceMap.SourceMapGenerator,
 				});
 
-				const sourceMap = compiled.map
+				const inlineSourceMap = compiled.map
 					? `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString('base64')}\n`
 					: '';
 
 				return {
-					contents: `${String(compiled.value)}${sourceMap}`,
+					contents: `${String(compiled.value)}${inlineSourceMap}`,
 					loader: compilerOptions?.jsx ? 'jsx' : 'js',
 					resolveDir: path.dirname(args.path),
 				};

package/src/mdx.plugin.d.ts

@@ -24,6 +24,18 @@ export declare class MDXPlugin extends IntegrationPlugin<EcoPagesElement> {
     private mdxLoaderPlugin;
     constructor({ compilerOptions, ...options }?: MDXPluginConfig);
     get plugins(): EcoBuildPlugin[];
+    /**
+     * Materializes the MDX loader once so config-time sealing and runtime setup
+     * can share the same loader instance.
+     */
+    private ensureLoaderPlugin;
+    /**
+     * Prepares the MDX loader contribution before config build seals the manifest.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Runs runtime-only MDX setup after build contributions are already prepared.
+     */
     setup(): Promise<void>;
 }
 /**

package/src/mdx.plugin.js

@@ -12,6 +12,18 @@ const defaultOptions = {
   jsxRuntime: "automatic",
   development: process.env.NODE_ENV === "development"
 };
+function splitMarkdownExtensions(extensions) {
+  const mdExtensions = [];
+  const mdxExtensions = [];
+  for (const extension of extensions) {
+    if (extension === ".md") {
+      mdExtensions.push(extension);
+      continue;
+    }
+    mdxExtensions.push(extension);
+  }
+  return { mdExtensions, mdxExtensions };
+}
 class MDXPlugin extends IntegrationPlugin {
   renderer;
   compilerOptions;
@@ -22,7 +34,15 @@ class MDXPlugin extends IntegrationPlugin {
       extensions: [".mdx"],
       ...options
     });
-    const finalCompilerOptions = deepMerge({ ...defaultOptions }, compilerOptions);
+    const { mdExtensions, mdxExtensions } = splitMarkdownExtensions(this.extensions);
+    const finalCompilerOptions = deepMerge(
+      {
+        ...defaultOptions,
+        mdxExtensions,
+        mdExtensions
+      },
+      compilerOptions
+    );
     const jsxImportSource = finalCompilerOptions.jsxImportSource;
     if (jsxImportSource === "react" || (jsxImportSource?.startsWith("react/") ?? false)) {
       throw new Error(
@@ -39,8 +59,27 @@ class MDXPlugin extends IntegrationPlugin {
     }
     return [];
   }
-  async setup() {
+  /**
+   * Materializes the MDX loader once so config-time sealing and runtime setup
+   * can share the same loader instance.
+   */
+  ensureLoaderPlugin() {
+    if (this.mdxLoaderPlugin) {
+      return;
+    }
     this.mdxLoaderPlugin = createMdxLoaderPlugin(this.compilerOptions);
+  }
+  /**
+   * Prepares the MDX loader contribution before config build seals the manifest.
+   */
+  async prepareBuildContributions() {
+    this.ensureLoaderPlugin();
+  }
+  /**
+   * Runs runtime-only MDX setup after build contributions are already prepared.
+   */
+  async setup() {
+    this.ensureLoaderPlugin();
     await super.setup();
   }
 }

package/src/mdx.plugin.ts

@@ -26,6 +26,31 @@ const defaultOptions: CompileOptions = {
 	development: process.env.NODE_ENV === 'development',
 };
 
+/**
+ * Splits configured markdown extensions into the two buckets understood by the
+ * MDX loader.
+ *
+ * `.mdx` remains the native MDX extension list. `.md` is special: it is only
+ * treated as MDX when a caller explicitly opts it into the pipeline, so we keep
+ * it separate rather than hiding that behavior inside a pair of constructor
+ * filters.
+ */
+function splitMarkdownExtensions(extensions: string[]): Pick<CompileOptions, 'mdExtensions' | 'mdxExtensions'> {
+	const mdExtensions: string[] = [];
+	const mdxExtensions: string[] = [];
+
+	for (const extension of extensions) {
+		if (extension === '.md') {
+			mdExtensions.push(extension);
+			continue;
+		}
+
+		mdxExtensions.push(extension);
+	}
+
+	return { mdExtensions, mdxExtensions };
+}
+
 /**
  * The MDX plugin class
  * This plugin provides support for MDX components in Ecopages.
@@ -46,7 +71,16 @@ export class MDXPlugin extends IntegrationPlugin<EcoPagesElement> {
 			...options,
 		});
 
-		const finalCompilerOptions = deepMerge({ ...defaultOptions }, compilerOptions);
+		const { mdExtensions, mdxExtensions } = splitMarkdownExtensions(this.extensions);
+
+		const finalCompilerOptions = deepMerge(
+			{
+				...defaultOptions,
+				mdxExtensions,
+				mdExtensions,
+			},
+			compilerOptions,
+		);
 		const jsxImportSource = finalCompilerOptions.jsxImportSource;
 
 		if (jsxImportSource === 'react' || (jsxImportSource?.startsWith('react/') ?? false)) {
@@ -69,8 +103,30 @@ export class MDXPlugin extends IntegrationPlugin<EcoPagesElement> {
 		return [];
 	}
 
-	override async setup(): Promise<void> {
+	/**
+	 * Materializes the MDX loader once so config-time sealing and runtime setup
+	 * can share the same loader instance.
+	 */
+	private ensureLoaderPlugin(): void {
+		if (this.mdxLoaderPlugin) {
+			return;
+		}
+
 		this.mdxLoaderPlugin = createMdxLoaderPlugin(this.compilerOptions);
+	}
+
+	/**
+	 * Prepares the MDX loader contribution before config build seals the manifest.
+	 */
+	override async prepareBuildContributions(): Promise<void> {
+		this.ensureLoaderPlugin();
+	}
+
+	/**
+	 * Runs runtime-only MDX setup after build contributions are already prepared.
+	 */
+	override async setup(): Promise<void> {
+		this.ensureLoaderPlugin();
 		await super.setup();
 	}
 }