@ecopages/mdx 0.2.0-alpha.8 → 0.2.1

package/CHANGELOG.md

@@ -4,30 +4,22 @@ All notable changes to `@ecopages/mdx` are documented here.
 
 > **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
 
-## [UNRELEASED] — TBD
+## [0.2.1] — 2026-04-16
 
 ### Features
 
-- 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.
+- Added standalone non-React MDX server rendering with async compilation and opt-in `.md` 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 the React-specific renderer and HMR code from the package and aligned MDX with the unified orchestration pipeline.
+- Fixed loader registration, Node `source-map` interop, and renderer-owned mixed-boundary rendering for standalone MDX routes.
 
 ### Documentation
 
-- Updated the README for standalone MDX registration and the current integration setup.
+- Updated the README for standalone non-React MDX usage, `.md` opt-in handling, and compiler configuration.
 
 ---
 
 ## Migration Notes
 
-- 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.
+- Use `reactPlugin({ mdx: { enabled: true } })` for React-backed MDX routes; the standalone `@ecopages/mdx` plugin now targets non-React JSX runtimes.

package/README.md

@@ -1,6 +1,6 @@
 # @ecopages/mdx
 
-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.
+Integration plugin for standalone MDX support in Ecopages for non-React JSX runtimes such as `@kitajs/html`. Use it when MDX should render directly on the server without React hydration.
 
 ## Installation
 
@@ -29,6 +29,39 @@ By default, the standalone plugin uses:
 - `jsxImportSource: '@kitajs/html'`
 - `jsxRuntime: 'automatic'`
 
+## What This Integration Owns
+
+- `.mdx` route files.
+- Optional `.md` routes when you opt them into `extensions`.
+- MDX compilation against a non-React JSX runtime.
+
+## Configure Markdown Extensions
+
+Use `extensions` when both `.mdx` and `.md` files should run through the MDX loader.
+
+```ts
+import { mdxPlugin } from '@ecopages/mdx';
+
+mdxPlugin({
+	extensions: ['.mdx', '.md'],
+});
+```
+
+## Compiler Options
+
+Pass `compilerOptions` to add remark, rehype, or recma plugins while keeping the non-React JSX runtime managed by the integration.
+
+```ts
+import { mdxPlugin } from '@ecopages/mdx';
+
+mdxPlugin({
+	compilerOptions: {
+		remarkPlugins: [],
+		rehypePlugins: [],
+	},
+});
+```
+
 > [!WARNING]
 > React runtimes are intentionally rejected by this standalone plugin.
 

package/package.json

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

package/src/mdx-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the MDX renderer
  * @module
  */
-import type { EcoComponent, EcoComponentConfig, EcoPageFile, EcoPagesElement, GetMetadata, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, EcoPagesElement, GetMetadata, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 import type { AssetProcessingService, ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
 import type { CompileOptions } from '@mdx-js/mdx';
@@ -33,11 +33,12 @@ export declare class MDXRenderer extends IntegrationRenderer<EcoPagesElement> {
         compilerOptions?: CompileOptions;
     });
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    protected importPageFile(file: string): Promise<EcoPageFile<{
-        layout?: EcoComponent<any> | {
-            config: EcoComponentConfig | undefined;
-        };
-    }>>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(_file: string, pageModule: TPageModule): TPageModule;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("@ecopages/core").ComponentBoundaryRuntime;
     render({ params, query, props, locals, pageLocals, metadata, Page, HtmlTemplate, Layout, pageProps, }: MDXIntegrationRendererOpions): Promise<RouteRendererBody>;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/mdx-renderer.js

@@ -34,19 +34,17 @@ class MDXRenderer extends IntegrationRenderer {
     }
     return await this.resolveDependencies(components);
   }
-  async importPageFile(file) {
+  normalizeImportedPageFile(_file, pageModule) {
     try {
-      const {
-        default: Page,
-        config,
-        getMetadata
-      } = await super.importPageFile(file);
+      const mdxModule = pageModule;
+      const { default: Page, config, getMetadata } = mdxModule;
       if (typeof Page !== "function") {
         throw new Error("MDX file must export a default function");
       }
       const resolvedLayout = config?.layout;
       if (config) Page.config = config;
       return {
+        ...pageModule,
         default: Page,
         layout: resolvedLayout,
         getMetadata
@@ -55,6 +53,18 @@ class MDXRenderer extends IntegrationRenderer {
       invariant(false, `Error importing MDX file: ${error}`);
     }
   }
+  async renderComponent(input) {
+    return this.renderStringComponentBoundaryWithQueuedForeignBoundaries(
+      input,
+      input.component
+    );
+  }
+  createComponentBoundaryRuntime(options) {
+    return this.createQueuedBoundaryRuntime({
+      boundaryInput: options.boundaryInput,
+      rendererCache: options.rendererCache
+    });
+  }
   async render({
     params,
     query,
@@ -68,42 +78,31 @@ class MDXRenderer extends IntegrationRenderer {
     pageProps
   }) {
     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({
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
         metadata,
-        children,
         pageProps: pageProps || {}
       });
-      return this.DOC_TYPE + body;
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
     }
   }
   async renderToResponse(view, props, ctx) {
     try {
-      const Layout = view.config?.layout;
-      const viewFn = view;
-      const pageContent = await viewFn(props);
-      let body;
-      if (ctx.partial) {
-        body = pageContent;
-      } else {
-        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-        const HtmlTemplate = await this.getHtmlTemplate();
-        const metadata = view.metadata ? await view.metadata({
-          params: {},
-          query: {},
-          props,
-          appConfig: this.appConfig
-        }) : this.appConfig.defaultMetadata;
-        body = this.DOC_TYPE + await HtmlTemplate({
-          metadata,
-          children,
-          pageProps: props
-        });
-      }
-      return this.createHtmlResponse(body, ctx);
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: view.config?.layout
+      });
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

package/src/mdx-loader-plugin.ts

@@ -1,63 +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 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'];
-	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,
-					format: resolveCompileFormat(filePath, compilerOptions),
-					SourceMapGenerator: sourceMap.SourceMapGenerator,
-				});
-
-				const inlineSourceMap = compiled.map
-					? `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString('base64')}\n`
-					: '';
-
-				return {
-					contents: `${String(compiled.value)}${inlineSourceMap}`,
-					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,141 +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',
-};
-
-/**
- * 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.
- *
- * 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 { 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(
-				'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 [];
-	}
-
-	/**
-	 * 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();
-	}
-}
-
-/**
- * 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);
-}