@ecopages/mdx 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+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
+
+### 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.
+
+### 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`).
+
+### Documentation
+
+- README updated to clarify the integration is now usable without the React integration.
+
+---
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Andrea Zanenghi
+
+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,52 @@
+# Ecopages MDX Integration Plugin
+
+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.
+
+## Install
+
+```bash
+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:
+
+```ts
+import { ConfigBuilder } from '@ecopages/core';
+import { mdxPlugin } from '@ecopages/mdx';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([mdxPlugin()])
+	.build();
+
+export default config;
+```
+
+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.
+
+## Using MDX with React Router
+
+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:
+
+```ts
+import { reactPlugin } from '@ecopages/react';
+import { ecoRouter } from '@ecopages/react-router';
+
+reactPlugin({
+	router: ecoRouter(),
+	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

@@ -0,0 +1,49 @@
+{
+  "name": "@ecopages/mdx",
+  "version": "0.2.0-alpha.1",
+  "description": "MDX plugin for Ecopages",
+  "keywords": [
+    "ecopages",
+    "mdx",
+    "plugin"
+  ],
+  "license": "MIT",
+  "main": "./src/mdx.plugin.js",
+  "types": "./src/mdx.plugin.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/mdx.plugin.js",
+      "types": "./src/mdx.plugin.d.ts"
+    },
+    "./declarations": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./mdx-loader-plugin": {
+      "default": "./src/mdx-loader-plugin.js",
+      "types": "./src/mdx-loader-plugin.d.ts"
+    },
+    "./declarations.ts": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./mdx-loader-plugin.ts": {
+      "default": "./src/mdx-loader-plugin.js",
+      "types": "./src/mdx-loader-plugin.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/integrations/mdx"
+  },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.1",
+    "@kitajs/html": "^4.1.0",
+    "@mdx-js/mdx": "^3.1.0"
+  },
+  "dependencies": {
+    "@ecopages/logger": "^0.2.2",
+    "source-map": "^0.7.6",
+    "vfile": "^6.0.3"
+  }
+}

package/src/declarations.d.ts

@@ -0,0 +1,8 @@
+declare module '*.mdx' {
+	import type { EcoComponent, EcoComponentConfig, EcoPagesElement, GetMetadata } from '@ecopages/core';
+
+	const MDXComponent: EcoComponent<Record<string, unknown>>;
+	export const config: EcoComponentConfig | undefined;
+	export const getMetadata: GetMetadata | undefined;
+	export default MDXComponent;
+}

package/src/mdx-loader-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { type CompileOptions } from '@mdx-js/mdx';
+export declare function createMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuildPlugin;

package/src/mdx-loader-plugin.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { compile } from "@mdx-js/mdx";
+import { SourceMapGenerator } from "source-map";
+import { VFile } from "vfile";
+function createMdxLoaderPlugin(compilerOptions) {
+  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 ? `
+//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString("base64")}
+` : "";
+        return {
+          contents: `${String(compiled.value)}${sourceMap}`,
+          loader: compilerOptions?.jsx ? "jsx" : "js",
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+}
+export {
+  createMdxLoaderPlugin
+};

package/src/mdx-loader-plugin.ts

@@ -0,0 +1,40 @@
+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.d.ts

@@ -0,0 +1,51 @@
+/**
+ * This module contains the MDX renderer
+ * @module
+ */
+import type { 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';
+/**
+ * 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 declare class MDXRenderer extends IntegrationRenderer<EcoPagesElement> {
+    name: string;
+    compilerOptions: CompileOptions;
+    constructor({ compilerOptions, ...options }: {
+        appConfig: any;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies: ProcessedAsset[];
+        runtimeOrigin: string;
+        compilerOptions?: CompileOptions;
+    });
+    buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
+    protected importPageFile(file: string): Promise<EcoPageFile<{
+        layout?: EcoComponent<any> | {
+            config: EcoComponentConfig | undefined;
+        };
+    }>>;
+    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>;
+}
+/**
+ * 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 declare function createMDXRenderer(compilerOptions: CompileOptions): typeof MDXRenderer;
+export {};

package/src/mdx-renderer.js

@@ -0,0 +1,125 @@
+import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
+import { invariant } from "@ecopages/core/utils/invariant";
+import { PLUGIN_NAME } from "./mdx.plugin.js";
+import { rapidhash } from "@ecopages/core/hash";
+class MDXRenderer extends IntegrationRenderer {
+  name = PLUGIN_NAME;
+  compilerOptions;
+  constructor({
+    compilerOptions,
+    ...options
+  }) {
+    super(options);
+    this.compilerOptions = compilerOptions || {};
+  }
+  async buildRouteRenderAssets(pagePath) {
+    const { default: pageComponent } = await this.importPageFile(pagePath);
+    const config = pageComponent.config;
+    const components = [];
+    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);
+  }
+  async importPageFile(file) {
+    try {
+      const {
+        default: Page,
+        config,
+        getMetadata
+      } = await super.importPageFile(file);
+      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
+  }) {
+    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(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);
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+}
+function createMDXRenderer(compilerOptions) {
+  return class extends MDXRenderer {
+    constructor(options) {
+      super({
+        ...options,
+        compilerOptions
+      });
+    }
+  };
+}
+export {
+  MDXRenderer,
+  createMDXRenderer
+};

package/src/mdx-renderer.ts

@@ -0,0 +1,221 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,34 @@
+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 type { CompileOptions } from '@mdx-js/mdx';
+import { MDXRenderer } from './mdx-renderer.js';
+/**
+ * The name of the MDX plugin
+ */
+export declare const PLUGIN_NAME = "MDX";
+export type MDXPluginConfig = Partial<Omit<IntegrationPluginConfig, 'name'>> & {
+    compilerOptions?: CompileOptions;
+};
+/**
+ * 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 declare class MDXPlugin extends IntegrationPlugin<EcoPagesElement> {
+    renderer: typeof MDXRenderer;
+    private compilerOptions;
+    private mdxLoaderPlugin;
+    constructor({ compilerOptions, ...options }?: MDXPluginConfig);
+    get plugins(): EcoBuildPlugin[];
+    setup(): Promise<void>;
+}
+/**
+ * Factory function to create an MDX plugin instance.
+ * @param options Configuration options for the MDX plugin
+ * @returns A new MDXPlugin instance
+ */
+export declare function mdxPlugin(options?: MDXPluginConfig): MDXPlugin;

package/src/mdx.plugin.js

@@ -0,0 +1,54 @@
+import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+import { deepMerge } from "@ecopages/core/utils/deep-merge";
+import { Logger } from "@ecopages/logger";
+import { createMdxLoaderPlugin } from "./mdx-loader-plugin.js";
+import { createMDXRenderer, MDXRenderer } from "./mdx-renderer.js";
+const appLogger = new Logger("[MDXPlugin]");
+const PLUGIN_NAME = "MDX";
+const defaultOptions = {
+  format: "detect",
+  outputFormat: "program",
+  jsxImportSource: "@kitajs/html",
+  jsxRuntime: "automatic",
+  development: process.env.NODE_ENV === "development"
+};
+class MDXPlugin extends IntegrationPlugin {
+  renderer;
+  compilerOptions;
+  mdxLoaderPlugin;
+  constructor({ compilerOptions, ...options } = { 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"}`);
+  }
+  get plugins() {
+    if (this.mdxLoaderPlugin) {
+      return [this.mdxLoaderPlugin];
+    }
+    return [];
+  }
+  async setup() {
+    this.mdxLoaderPlugin = createMdxLoaderPlugin(this.compilerOptions);
+    await super.setup();
+  }
+}
+function mdxPlugin(options) {
+  return new MDXPlugin(options);
+}
+export {
+  MDXPlugin,
+  PLUGIN_NAME,
+  mdxPlugin
+};

package/src/mdx.plugin.ts

@@ -0,0 +1,85 @@
+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);
+}