@ecopages/mdx 0.2.0-alpha.1 → 0.2.0-alpha.10

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.1",
+  "version": "0.2.0-alpha.10",
   "description": "MDX plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -37,7 +37,7 @@
     "directory": "packages/integrations/mdx"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.1",
+    "@ecopages/core": "0.2.0-alpha.10",
     "@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.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-loader-plugin.ts

@@ -1,40 +0,0 @@
-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 { VFile } from 'vfile';
-
-export function createMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuildPlugin {
-	const mdxExtensions = compilerOptions?.mdxExtensions ?? ['.mdx'];
-	const mdExtensions = compilerOptions?.mdExtensions ?? ['.md'];
-	const allExtensions = [...mdxExtensions, ...mdExtensions];
-	const escapedExts = allExtensions.map((ext) => ext.replace('.', '\\.'));
-	const filter = new RegExp(`(${escapedExts.join('|')})(\\?.*)?$`);
-
-	return {
-		name: 'mdx-loader',
-		setup(build) {
-			build.onLoad({ filter }, async (args) => {
-				const filePath = args.path.includes('?') ? args.path.split('?')[0] : args.path;
-				const source = readFileSync(filePath, 'utf-8');
-				const file = new VFile({ path: filePath, value: source });
-
-				const compiled = await compile(file, {
-					...compilerOptions,
-					SourceMapGenerator,
-				});
-
-				const sourceMap = compiled.map
-					? `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString('base64')}\n`
-					: '';
-
-				return {
-					contents: `${String(compiled.value)}${sourceMap}`,
-					loader: compilerOptions?.jsx ? 'jsx' : 'js',
-					resolveDir: path.dirname(args.path),
-				};
-			});
-		},
-	};
-}

package/src/mdx-renderer.ts

@@ -1,221 +0,0 @@
-/**
- * This module contains the MDX renderer
- * @module
- */
-
-import type {
-	EcoComponent,
-	EcoComponentConfig,
-	EcoPageFile,
-	EcoPagesElement,
-	GetMetadata,
-	IntegrationRendererRenderOptions,
-	PageMetadataProps,
-	RouteRendererBody,
-} from '@ecopages/core';
-import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
-import { invariant } from '@ecopages/core/utils/invariant';
-import type { AssetProcessingService, ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
-import type { CompileOptions } from '@mdx-js/mdx';
-import { PLUGIN_NAME } from './mdx.plugin.ts';
-import { rapidhash } from '@ecopages/core/hash';
-
-/**
- * A structure representing an MDX file
- */
-export type MDXFile = {
-	default: EcoComponent;
-	config?: EcoComponentConfig;
-	getMetadata: GetMetadata;
-};
-
-/**
- * Options for the MDX renderer
- */
-interface MDXIntegrationRendererOpions<C = EcoPagesElement> extends IntegrationRendererRenderOptions<C> {}
-
-/**
- * A renderer for the MDX integration.
- */
-export class MDXRenderer extends IntegrationRenderer<EcoPagesElement> {
-	name = PLUGIN_NAME;
-	compilerOptions: CompileOptions;
-
-	constructor({
-		compilerOptions,
-		...options
-	}: {
-		appConfig: any;
-		assetProcessingService: AssetProcessingService;
-		resolvedIntegrationDependencies: ProcessedAsset[];
-		runtimeOrigin: string;
-		compilerOptions?: CompileOptions;
-	}) {
-		super(options);
-		this.compilerOptions = compilerOptions || {};
-	}
-
-	override async buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]> {
-		const { default: pageComponent } = await this.importPageFile(pagePath);
-		const config = pageComponent.config;
-		const components: Partial<EcoComponent>[] = [];
-
-		const resolvedLayout = config?.layout;
-
-		if (resolvedLayout?.config?.dependencies) {
-			components.push({ config: resolvedLayout.config });
-		}
-
-		if (config?.dependencies) {
-			components.push({
-				config: {
-					...config,
-					__eco: {
-						id: rapidhash(pagePath).toString(36),
-						file: pagePath,
-						integration: this.name,
-					},
-				},
-			});
-		}
-
-		return await this.resolveDependencies(components);
-	}
-
-	protected override async importPageFile(file: string): Promise<
-		EcoPageFile<{
-			layout?:
-				| EcoComponent<any>
-				| {
-						config: EcoComponentConfig | undefined;
-				  };
-		}>
-	> {
-		try {
-			const {
-				default: Page,
-				config,
-				getMetadata,
-			} = (await super.importPageFile(file)) as EcoPageFile<{
-				layout?:
-					| EcoComponent<any>
-					| {
-							config: EcoComponentConfig | undefined;
-					  };
-			}> & {
-				config?: EcoComponentConfig;
-			};
-
-			if (typeof Page !== 'function') {
-				throw new Error('MDX file must export a default function');
-			}
-
-			const resolvedLayout = config?.layout;
-
-			if (config) Page.config = config;
-
-			return {
-				default: Page,
-				layout: resolvedLayout,
-				getMetadata,
-			};
-		} catch (error) {
-			invariant(false, `Error importing MDX file: ${error}`);
-		}
-	}
-
-	async render({
-		params,
-		query,
-		props,
-		locals,
-		pageLocals,
-		metadata,
-		Page,
-		HtmlTemplate,
-		Layout,
-		pageProps,
-	}: MDXIntegrationRendererOpions): Promise<RouteRendererBody> {
-		try {
-			const pageContent = await Page({ params, query, ...props, locals: pageLocals });
-			const children =
-				typeof Layout === 'function' ? await Layout({ children: pageContent, locals }) : pageContent;
-
-			const body = await HtmlTemplate({
-				metadata,
-				children,
-				pageProps: pageProps || {},
-			});
-
-			return this.DOC_TYPE + body;
-		} catch (error) {
-			throw this.createRenderError('Error rendering page', error);
-		}
-	}
-
-	async renderToResponse<P = Record<string, unknown>>(
-		view: EcoComponent<P>,
-		props: P,
-		ctx: RenderToResponseContext,
-	): Promise<Response> {
-		try {
-			const Layout = view.config?.layout as
-				| ((props: { children: EcoPagesElement } & Record<string, unknown>) => Promise<EcoPagesElement>)
-				| undefined;
-
-			const viewFn = view as (props: P) => Promise<EcoPagesElement>;
-			const pageContent = await viewFn(props);
-
-			let body: string;
-			if (ctx.partial) {
-				body = pageContent as string;
-			} else {
-				const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-
-				const HtmlTemplate = await this.getHtmlTemplate();
-				const metadata: PageMetadataProps = view.metadata
-					? await view.metadata({
-							params: {},
-							query: {},
-							props: props as Record<string, unknown>,
-							appConfig: this.appConfig,
-						})
-					: this.appConfig.defaultMetadata;
-
-				body =
-					this.DOC_TYPE +
-					(await HtmlTemplate({
-						metadata,
-						children: children as EcoPagesElement,
-						pageProps: props as Record<string, unknown>,
-					}));
-			}
-
-			return this.createHtmlResponse(body, ctx);
-		} catch (error) {
-			throw this.createRenderError('Error rendering view', error);
-		}
-	}
-}
-
-/**
- * Factory function to create an MDX renderer class with specific compiler options.
- *
- * @param compilerOptions - Compiler options for MDX compilation.
- * @returns A new MDXRenderer class extended with the provided context.
- */
-export function createMDXRenderer(compilerOptions: CompileOptions): typeof MDXRenderer {
-	return class extends MDXRenderer {
-		constructor(options: {
-			appConfig: any;
-			assetProcessingService: AssetProcessingService;
-			resolvedIntegrationDependencies: ProcessedAsset[];
-			runtimeOrigin: string;
-		}) {
-			super({
-				...options,
-				compilerOptions,
-			});
-		}
-	};
-}

package/src/mdx.plugin.ts

@@ -1,85 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { EcoPagesElement } from '@ecopages/core';
-import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
-import { deepMerge } from '@ecopages/core/utils/deep-merge';
-import { Logger } from '@ecopages/logger';
-import type { CompileOptions } from '@mdx-js/mdx';
-import { createMdxLoaderPlugin } from './mdx-loader-plugin.ts';
-import { createMDXRenderer, MDXRenderer } from './mdx-renderer.ts';
-
-const appLogger = new Logger('[MDXPlugin]');
-
-/**
- * The name of the MDX plugin
- */
-export const PLUGIN_NAME = 'MDX';
-
-export type MDXPluginConfig = Partial<Omit<IntegrationPluginConfig, 'name'>> & {
-	compilerOptions?: CompileOptions;
-};
-
-const defaultOptions: CompileOptions = {
-	format: 'detect',
-	outputFormat: 'program',
-	jsxImportSource: '@kitajs/html',
-	jsxRuntime: 'automatic',
-	development: process.env.NODE_ENV === 'development',
-};
-
-/**
- * The MDX plugin class
- * This plugin provides support for MDX components in Ecopages.
- *
- * Standalone `mdxPlugin()` is intended for non-React JSX runtimes such as
- * `@kitajs/html`. React-backed MDX should be configured through
- * `reactPlugin({ mdx: { enabled: true, compilerOptions: ... } })` instead.
- */
-export class MDXPlugin extends IntegrationPlugin<EcoPagesElement> {
-	renderer: typeof MDXRenderer;
-	private compilerOptions: CompileOptions;
-	private mdxLoaderPlugin: EcoBuildPlugin | undefined;
-
-	constructor({ compilerOptions, ...options }: MDXPluginConfig = { extensions: ['.mdx'] }) {
-		super({
-			name: PLUGIN_NAME,
-			extensions: ['.mdx'],
-			...options,
-		});
-
-		const finalCompilerOptions = deepMerge({ ...defaultOptions }, compilerOptions);
-		const jsxImportSource = finalCompilerOptions.jsxImportSource;
-
-		if (jsxImportSource === 'react' || (jsxImportSource?.startsWith('react/') ?? false)) {
-			throw new Error(
-				'Standalone `mdxPlugin()` does not support React JSX runtimes. Use `reactPlugin({ mdx: { enabled: true, compilerOptions: ... } })` instead.',
-			);
-		}
-
-		this.compilerOptions = finalCompilerOptions;
-		this.renderer = createMDXRenderer(finalCompilerOptions);
-
-		appLogger.debug(`MDX plugin configured with jsxImportSource: ${jsxImportSource ?? 'default'}`);
-	}
-
-	override get plugins(): EcoBuildPlugin[] {
-		if (this.mdxLoaderPlugin) {
-			return [this.mdxLoaderPlugin];
-		}
-
-		return [];
-	}
-
-	override async setup(): Promise<void> {
-		this.mdxLoaderPlugin = createMdxLoaderPlugin(this.compilerOptions);
-		await super.setup();
-	}
-}
-
-/**
- * Factory function to create an MDX plugin instance.
- * @param options Configuration options for the MDX plugin
- * @returns A new MDXPlugin instance
- */
-export function mdxPlugin(options?: MDXPluginConfig): MDXPlugin {
-	return new MDXPlugin(options);
-}