@ecopages/postcss-processor 0.2.0-alpha.1 → 0.2.0-alpha.3

package/src/plugin.ts

@@ -23,6 +23,16 @@ const logger = new Logger('[@ecopages/postcss-processor]', {
  */
 export type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
 
+/**
+ * Lazily creates PostCSS plugins.
+ *
+ * This is primarily used in development when a non-CSS file change forces the
+ * processor to rebuild tracked stylesheets. Some plugins, including Tailwind,
+ * keep internal caches in long-lived plugin instances, so recreating them is
+ * required to pick up newly discovered classes.
+ */
+export type PluginFactoryRecord = Record<string, () => postcss.AcceptedPlugin>;
+
 /**
  * Configuration for the PostCSS processor
  */
@@ -52,6 +62,13 @@ export interface PostCssProcessorPluginConfig {
 	 * @default undefined (uses default plugins)
 	 */
 	plugins?: PluginsRecord;
+	/**
+	 * Factory functions for recreating stateful PostCSS plugins.
+	 *
+	 * When provided, Ecopages uses these factories to build a fresh plugin list
+	 * for dependency-driven stylesheet rebuilds during development.
+	 */
+	pluginFactories?: PluginFactoryRecord;
 }
 
 /**
@@ -64,7 +81,10 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 	};
 
 	private postcssPlugins: postcss.AcceptedPlugin[] = [];
+	private pluginFactories?: PluginFactoryRecord;
 	private readonly runtimeCssCache = new Map<string, string>();
+	private readonly trackedCssFiles = new Set<string>();
+	private watchQueue: Promise<void> = Promise.resolve();
 
 	private getCssFilter(): RegExp {
 		return this.options?.filter ?? PostCssProcessorPlugin.DEFAULT_OPTIONS.filter;
@@ -117,6 +137,8 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 				continue;
 			}
 
+			this.trackedCssFiles.add(filePath);
+
 			const rawContents = await fileSystem.readFile(filePath);
 			let transformedInput = rawContents;
 
@@ -169,6 +191,47 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 		return filter.test(filepath);
 	}
 
+	private materializePluginFactories(pluginFactories: PluginFactoryRecord): postcss.AcceptedPlugin[] {
+		return Object.values(pluginFactories).map((factory) => factory());
+	}
+
+	private refreshConfiguredPlugins(): void {
+		if (!this.pluginFactories) {
+			return;
+		}
+
+		this.postcssPlugins = this.materializePluginFactories(this.pluginFactories);
+	}
+
+	private enqueueWatchTask(task: () => Promise<void>): Promise<void> {
+		const queuedTask = this.watchQueue.then(task, task);
+		this.watchQueue = queuedTask.catch(() => undefined);
+		return queuedTask;
+	}
+
+	private getTrackedCssFiles(): string[] {
+		return Array.from(this.trackedCssFiles).filter(
+			(filePath) => this.matchesFileFilter(filePath) && fileSystem.exists(filePath),
+		);
+	}
+
+	private async handleDependencyChange(bridge: IClientBridge): Promise<void> {
+		if (!this.context) {
+			return;
+		}
+
+		const cssFiles = this.getTrackedCssFiles();
+		if (cssFiles.length === 0) {
+			return;
+		}
+
+		this.refreshConfiguredPlugins();
+
+		for (const cssFilePath of cssFiles) {
+			await this.handleCssChange(cssFilePath, bridge, false);
+		}
+	}
+
 	constructor(
 		config: Omit<ProcessorConfig<PostCssProcessorPluginConfig>, 'name' | 'description'> = {
 			options: PostCssProcessorPlugin.DEFAULT_OPTIONS,
@@ -180,14 +243,55 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 			capabilities: [
 				{
 					kind: 'stylesheet',
-					extensions: ['*.css'],
+					extensions: ['*.{css,scss,sass,less}'],
 				},
 			],
 			watch: {
 				paths: [],
-				extensions: ['.css', '.scss', '.sass', '.less'],
+				extensions: [
+					'.css',
+					'.scss',
+					'.sass',
+					'.less',
+					'.tsx',
+					'.ts',
+					'.jsx',
+					'.js',
+					'.mdx',
+					'.html',
+					'.svelte',
+					'.vue',
+				],
 				onChange: async ({ path, bridge }) => {
-					await this.handleCssChange(path, bridge);
+					await this.enqueueWatchTask(async () => {
+						if (this.matchesFileFilter(path)) {
+							await this.handleCssChange(path, bridge);
+							return;
+						}
+
+						await this.handleDependencyChange(bridge);
+					});
+				},
+				onCreate: async ({ path, bridge }) => {
+					await this.enqueueWatchTask(async () => {
+						if (this.matchesFileFilter(path)) {
+							await this.handleCssChange(path, bridge);
+							return;
+						}
+
+						await this.handleDependencyChange(bridge);
+					});
+				},
+				onDelete: async ({ path, bridge }) => {
+					await this.enqueueWatchTask(async () => {
+						if (this.matchesFileFilter(path)) {
+							this.runtimeCssCache.delete(path);
+							this.trackedCssFiles.delete(path);
+							return;
+						}
+
+						await this.handleDependencyChange(bridge);
+					});
 				},
 			},
 			...config,
@@ -198,10 +302,17 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 	 * Handles CSS file changes during development.
 	 * Processes the file and broadcasts a css-update event for hot reloading.
 	 */
-	private async handleCssChange(filePath: string, bridge: IClientBridge): Promise<void> {
+	private async handleCssChange(filePath: string, bridge: IClientBridge, refreshPlugins = true): Promise<void> {
 		if (!this.context) return;
+		if (!fileSystem.exists(filePath)) return;
 
 		try {
+			this.trackedCssFiles.add(filePath);
+
+			if (refreshPlugins) {
+				this.refreshConfiguredPlugins();
+			}
+
 			let content = await fileSystem.readFile(filePath);
 
 			if (this.options?.transformInput) {
@@ -209,6 +320,12 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 			}
 
 			const processed = await this.process(content, filePath);
+
+			const cached = this.runtimeCssCache.get(filePath);
+			if (cached === processed) {
+				return;
+			}
+
 			this.runtimeCssCache.set(filePath, processed);
 			await this.persistProcessedCss(filePath, processed);
 
@@ -262,6 +379,7 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 		const configExtensions = ['js', 'cjs', 'mjs', 'ts'];
 		let foundConfigPath: string | undefined;
 		let loadedPlugins: postcss.AcceptedPlugin[] | undefined;
+		let loadedPluginFactories: PluginFactoryRecord | undefined;
 
 		for (const ext of configExtensions) {
 			const configPath = path.join(this.context.rootDir, `postcss.config.${ext}`);
@@ -277,6 +395,13 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 
 				const postcssConfigModule = await import(foundConfigPath);
 				const postcssConfig = postcssConfigModule.default || postcssConfigModule;
+				if (
+					postcssConfig &&
+					typeof postcssConfig.pluginFactories === 'object' &&
+					postcssConfig.pluginFactories !== null
+				) {
+					loadedPluginFactories = postcssConfig.pluginFactories as PluginFactoryRecord;
+				}
 
 				if (postcssConfig && typeof postcssConfig.plugins === 'object' && postcssConfig.plugins !== null) {
 					if (Array.isArray(postcssConfig.plugins)) {
@@ -298,16 +423,26 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 			logger.debug('No PostCSS config file found in root directory.');
 		}
 
-		if (loadedPlugins) {
+		if (loadedPluginFactories) {
+			this.pluginFactories = loadedPluginFactories;
+			this.postcssPlugins = this.materializePluginFactories(loadedPluginFactories);
+		} else if (loadedPlugins) {
+			this.pluginFactories = undefined;
 			this.postcssPlugins = loadedPlugins;
+		} else if (this.options?.pluginFactories) {
+			logger.debug('Using PostCSS plugin factories provided in processor options.');
+			this.pluginFactories = this.options.pluginFactories;
+			this.postcssPlugins = this.materializePluginFactories(this.options.pluginFactories);
 		} else if (this.options?.plugins) {
 			logger.debug('Using PostCSS plugins provided in processor options.');
+			this.pluginFactories = undefined;
 			this.postcssPlugins = Object.values(this.options.plugins);
 		} else {
 			logger.warn(
 				'No PostCSS plugins configured. Use a preset like tailwindV3Preset() or tailwindV4Preset(), ' +
 					'provide plugins via options, or create a postcss.config file.',
 			);
+			this.pluginFactories = undefined;
 			this.postcssPlugins = [];
 		}
 

package/src/postcss-processor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * This module contains the PostCSS Processor
+ * @module
+ */
+import postcss from 'postcss';
+/**
+ * PostCSS Processor Options
+ */
+export type PostCssProcessorOptions = {
+    plugins?: postcss.AcceptedPlugin[];
+    /**
+     * Optional file path for resolving relative imports
+     */
+    filePath?: string;
+    /**
+     * Optional callback to transform the output CSS
+     * @param css The processed CSS
+     * @returns The transformed CSS
+     */
+    transformOutput?: (css: string) => string | Promise<string>;
+};
+/**
+ * ProcessPath
+ * @param path string
+ * @param options {@link PostCssProcessorOptions}
+ * @returns string
+ */
+export type ProcessPath = (path: string, options?: PostCssProcessorOptions) => Promise<string>;
+/**
+ * ProcessStringOrBuffer
+ * @param contents string | Buffer
+ * @param options {@link PostCssProcessorOptions}
+ * @returns string
+ */
+export type ProcessStringOrBuffer = (contents: string | Buffer, options?: PostCssProcessorOptions) => Promise<string>;
+export declare function getFileAsBuffer(path: string): Buffer;
+export type ProcessStringOrBufferSync = (contents: string | Buffer, options?: PostCssProcessorOptions) => string;
+/**
+ * PostCSS Processor
+ * - {@link processPath} : It processes the given path using PostCSS
+ * - {@link processStringOrBuffer}: It processes the given string or buffer using PostCSS
+ * - {@link processStringOrBufferSync}: It processes the given string or buffer synchronously using PostCSS (requires all plugins to be sync)
+ */
+export declare const PostCssProcessor: {
+    processPath: ProcessPath;
+    processStringOrBuffer: ProcessStringOrBuffer;
+    processStringOrBufferSync: ProcessStringOrBufferSync;
+};

package/src/postcss-processor.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from "node:fs";
+import { Logger } from "@ecopages/logger";
+import postcss from "postcss";
+const appLogger = new Logger("[@ecopages/postcss-processor]");
+function getFileAsBuffer(path) {
+  try {
+    if (!existsSync(path)) {
+      throw new Error(`File: ${path} not found`);
+    }
+    return readFileSync(path);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`[ecopages] Error reading file: ${path}, ${errorMessage}`);
+  }
+}
+const getPlugins = (options) => {
+  if (!options || !options.plugins) return [];
+  return Array.isArray(options.plugins) ? options.plugins : Object.values(options.plugins);
+};
+const processPath = async (path, options) => {
+  const contents = getFileAsBuffer(path);
+  return postcss(getPlugins(options)).process(contents, { from: path }).then((result) => result.css).catch((error) => {
+    appLogger.error("Error processing file with PostCssProcessor", error.message);
+    return "";
+  });
+};
+const processStringOrBuffer = async (contents, options) => {
+  if (!contents) return "";
+  return postcss(getPlugins(options)).process(contents, { from: options?.filePath }).then(async (result) => {
+    let css = result.css;
+    if (options?.transformOutput) {
+      css = await options.transformOutput(css);
+    }
+    return css;
+  }).catch((error) => {
+    appLogger.error("Error processing string or buffer with PostCssProcessor", error.message);
+    return "";
+  });
+};
+const processStringOrBufferSync = (contents, options) => {
+  if (!contents) return "";
+  try {
+    const result = postcss(getPlugins(options)).process(contents, { from: options?.filePath });
+    let css = result.css;
+    if (options?.transformOutput) {
+      const output = options.transformOutput(css);
+      if (output instanceof Promise) {
+        throw new Error("transformOutput must be synchronous when used with processStringOrBufferSync");
+      }
+      css = output;
+    }
+    return css;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("transformOutput must be synchronous")) {
+      throw error;
+    }
+    appLogger.error("Error processing string or buffer with PostCssProcessor", error.message);
+    return "";
+  }
+};
+const PostCssProcessor = {
+  processPath,
+  processStringOrBuffer,
+  processStringOrBufferSync
+};
+export {
+  PostCssProcessor,
+  getFileAsBuffer
+};

package/src/presets/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PostCSS Processor Presets
+ * @module @ecopages/postcss-processor/presets
+ */
+export { tailwindV3Preset } from './tailwind-v3';
+export { tailwindV4Preset, type TailwindV4PresetOptions } from './tailwind-v4';

package/src/presets/index.js

@@ -0,0 +1,6 @@
+import { tailwindV3Preset } from "./tailwind-v3";
+import { tailwindV4Preset } from "./tailwind-v4";
+export {
+  tailwindV3Preset,
+  tailwindV4Preset
+};

package/src/presets/tailwind-v3.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tailwind CSS v3 Preset for PostCSS Processor
+ * @module @ecopages/postcss-processor/presets/tailwind-v3
+ *
+ * Requires: tailwindcss, postcss-import, autoprefixer, cssnano
+ * Install: bun add tailwindcss postcss-import autoprefixer cssnano
+ */
+import type { PostCssProcessorPluginConfig } from '../plugin.js';
+/**
+ * Creates a PostCSS processor config preset for Tailwind CSS v3.
+ *
+ * Features:
+ * - Uses classic Tailwind v3 plugin stack
+ * - Includes postcss-import, tailwindcss/nesting, tailwindcss, autoprefixer, cssnano
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
+ *
+ * @example
+ * ```typescript
+ * import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+ * import { tailwindV3Preset } from '@ecopages/postcss-processor/presets';
+ *
+ * // Basic usage
+ * postcssProcessorPlugin(tailwindV3Preset())
+ *
+ * // Extend with additional plugins
+ * const preset = tailwindV3Preset();
+ * postcssProcessorPlugin({
+ *   ...preset,
+ *   plugins: { ...preset.plugins, myPlugin: myPlugin() },
+ * })
+ * ```
+ */
+export declare function tailwindV3Preset(): PostCssProcessorPluginConfig;

package/src/presets/tailwind-v3.js

@@ -0,0 +1,26 @@
+import autoprefixer from "autoprefixer";
+import browserslist from "browserslist";
+import cssnano from "cssnano";
+import postcssImport from "postcss-import";
+import tailwindcss from "tailwindcss";
+import tailwindcssNesting from "tailwindcss/nesting/index.js";
+function tailwindV3Preset() {
+  const browserslistConfig = browserslist.loadConfig({ path: process.cwd() });
+  const autoprefixerOptions = browserslistConfig ? {} : {
+    overrideBrowserslist: [">0.3%", "not ie 11", "not dead", "not op_mini all"]
+  };
+  const pluginFactories = {
+    "postcss-import": () => postcssImport(),
+    "tailwindcss/nesting": () => tailwindcssNesting(),
+    tailwindcss: () => tailwindcss(),
+    autoprefixer: () => autoprefixer(autoprefixerOptions),
+    cssnano: () => cssnano()
+  };
+  const plugins = Object.fromEntries(
+    Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])
+  );
+  return { plugins, pluginFactories };
+}
+export {
+  tailwindV3Preset
+};

package/src/presets/tailwind-v3.ts

@@ -13,7 +13,7 @@ import type postcss from 'postcss';
 import postcssImport from 'postcss-import';
 import tailwindcss from 'tailwindcss';
 import tailwindcssNesting from 'tailwindcss/nesting/index.js';
-import type { PostCssProcessorPluginConfig } from '../plugin.ts';
+import type { PluginFactoryRecord, PostCssProcessorPluginConfig } from '../plugin.ts';
 
 type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
 
@@ -23,6 +23,8 @@ type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
  * Features:
  * - Uses classic Tailwind v3 plugin stack
  * - Includes postcss-import, tailwindcss/nesting, tailwindcss, autoprefixer, cssnano
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
  *
  * @example
  * ```typescript
@@ -49,13 +51,22 @@ export function tailwindV3Preset(): PostCssProcessorPluginConfig {
 				overrideBrowserslist: ['>0.3%', 'not ie 11', 'not dead', 'not op_mini all'],
 			};
 
-	const plugins: PluginsRecord = {
-		'postcss-import': postcssImport(),
-		'tailwindcss/nesting': tailwindcssNesting(),
-		tailwindcss: tailwindcss(),
-		autoprefixer: autoprefixer(autoprefixerOptions),
-		cssnano: cssnano(),
+	const pluginFactories: PluginFactoryRecord = {
+		'postcss-import': () => postcssImport(),
+		'tailwindcss/nesting': () => tailwindcssNesting(),
+		tailwindcss: () => tailwindcss(),
+		autoprefixer: () => autoprefixer(autoprefixerOptions),
+		cssnano: () => cssnano(),
 	};
 
-	return { plugins };
+	const plugins: PluginsRecord = Object.fromEntries(
+		Object.entries(pluginFactories).map(([name, factory]) => [name, factory()]),
+	) as PluginsRecord;
+
+	/**
+	 * Keep both forms:
+	 * - `plugins` are used immediately by the processor
+	 * - `pluginFactories` let the processor recreate fresh plugin instances later
+	 */
+	return { plugins, pluginFactories };
 }

package/src/presets/tailwind-v4.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Tailwind CSS v4 Preset for PostCSS Processor
+ * @module @ecopages/postcss-processor/presets/tailwind-v4
+ *
+ * Requires: @tailwindcss/postcss, cssnano
+ * Install: bun add @tailwindcss/postcss cssnano
+ */
+import type { PostCssProcessorPluginConfig } from '../plugin.js';
+/**
+ * Options for Tailwind v4 preset
+ */
+export interface TailwindV4PresetOptions {
+    /**
+     * Absolute path to the main Tailwind CSS file containing `@import "tailwindcss"`.
+     * Used to calculate relative @reference paths for CSS files using @apply.
+     */
+    referencePath: string;
+}
+/**
+ * Creates a PostCSS processor config preset for Tailwind CSS v4.
+ *
+ * Features:
+ * - Uses `@tailwindcss/postcss` plugin (v4)
+ * - Automatically injects `@reference` headers for `@apply` support
+ * - Includes cssnano for CSS minification
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
+ *
+ * @example
+ * ```typescript
+ * import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+ * import { tailwindV4Preset } from '@ecopages/postcss-processor/presets';
+ *
+ * // Basic usage
+ * postcssProcessorPlugin(tailwindV4Preset({
+ *   referencePath: path.resolve(import.meta.dir, 'src/styles/tailwind.css'),
+ * }))
+ *
+ * // Extend with additional plugins
+ * const preset = tailwindV4Preset({ referencePath });
+ * postcssProcessorPlugin({
+ *   ...preset,
+ *   plugins: { ...preset.plugins, myPlugin: myPlugin() },
+ * })
+ * ```
+ */
+export declare function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProcessorPluginConfig;

package/src/presets/tailwind-v4.js

@@ -0,0 +1,57 @@
+import tailwindcss from "@tailwindcss/postcss";
+import autoprefixer from "autoprefixer";
+import browserslist from "browserslist";
+import cssnano from "cssnano";
+import path from "node:path";
+import postcssImport from "postcss-import";
+import postcssNested from "postcss-nested";
+function tailwindV4Preset(options) {
+  const { referencePath } = options;
+  const browserslistConfig = browserslist.loadConfig({ path: process.cwd() });
+  const autoprefixerOptions = browserslistConfig ? {} : {
+    overrideBrowserslist: [">0.3%", "not ie 11", "not dead", "not op_mini all"]
+  };
+  const pluginFactories = {
+    "postcss-import": () => postcssImport(),
+    "postcss-nested": () => postcssNested(),
+    "@tailwindcss/postcss": () => tailwindcss(),
+    autoprefixer: () => autoprefixer(autoprefixerOptions),
+    cssnano: () => cssnano()
+  };
+  return {
+    /**
+     * Instantiate the initial plugin list for the active processor instance.
+     * Fresh instances can later be recreated from `pluginFactories`.
+     */
+    plugins: Object.fromEntries(Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])),
+    pluginFactories,
+    transformInput: async (contents, filePath) => {
+      const css = contents instanceof Buffer ? contents.toString("utf-8") : contents;
+      const normalizedFilePath = path.resolve(filePath);
+      const normalizedReferencePath = path.resolve(referencePath);
+      if (normalizedFilePath === normalizedReferencePath) {
+        return css;
+      }
+      if (/^\s*@reference\s+/m.test(css)) {
+        return css;
+      }
+      const relativePath = path.relative(path.dirname(filePath), referencePath);
+      if (css.includes(`@import '${relativePath}'`) || css.includes(`@import "${relativePath}"`)) {
+        return css;
+      }
+      const tailwindImportPattern = /^@import\s+['"]tailwindcss(?:\/[^'"]*)?['"];?\s*$/m;
+      if (tailwindImportPattern.test(css)) {
+        return css.replace(tailwindImportPattern, `@import '${relativePath}';`);
+      }
+      if (css.includes("@apply")) {
+        return `@reference "${relativePath}";
+
+${css}`;
+      }
+      return css;
+    }
+  };
+}
+export {
+  tailwindV4Preset
+};

package/src/presets/tailwind-v4.ts

@@ -13,7 +13,7 @@ import cssnano from 'cssnano';
 import path from 'node:path';
 import postcssImport from 'postcss-import';
 import postcssNested from 'postcss-nested';
-import type { PostCssProcessorPluginConfig } from '../plugin.ts';
+import type { PluginFactoryRecord, PostCssProcessorPluginConfig } from '../plugin.ts';
 
 /**
  * Options for Tailwind v4 preset
@@ -33,6 +33,8 @@ export interface TailwindV4PresetOptions {
  * - Uses `@tailwindcss/postcss` plugin (v4)
  * - Automatically injects `@reference` headers for `@apply` support
  * - Includes cssnano for CSS minification
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
  *
  * @example
  * ```typescript
@@ -63,14 +65,21 @@ export function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProce
 				overrideBrowserslist: ['>0.3%', 'not ie 11', 'not dead', 'not op_mini all'],
 			};
 
+	const pluginFactories: PluginFactoryRecord = {
+		'postcss-import': () => postcssImport(),
+		'postcss-nested': () => postcssNested(),
+		'@tailwindcss/postcss': () => tailwindcss(),
+		autoprefixer: () => autoprefixer(autoprefixerOptions),
+		cssnano: () => cssnano(),
+	};
+
 	return {
-		plugins: {
-			'postcss-import': postcssImport(),
-			'postcss-nested': postcssNested(),
-			'@tailwindcss/postcss': tailwindcss(),
-			autoprefixer: autoprefixer(autoprefixerOptions),
-			cssnano: cssnano(),
-		},
+		/**
+		 * Instantiate the initial plugin list for the active processor instance.
+		 * Fresh instances can later be recreated from `pluginFactories`.
+		 */
+		plugins: Object.fromEntries(Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])),
+		pluginFactories,
 		transformInput: async (contents: string | Buffer, filePath: string): Promise<string> => {
 			const css = contents instanceof Buffer ? contents.toString('utf-8') : (contents as string);
 			const normalizedFilePath = path.resolve(filePath);

package/src/runtime/css-loader-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { CssTransform } from './css-runtime-contract';
+type CssLoaderOptions = {
+    name: string;
+    filter: RegExp;
+    transform: CssTransform;
+};
+export declare const createCssLoaderPlugin: ({ name, filter, transform }: CssLoaderOptions) => EcoBuildPlugin;
+export {};

package/src/runtime/css-loader-plugin.js

@@ -0,0 +1,28 @@
+import { getFileAsBuffer } from "../postcss-processor";
+const createCssLoaderPlugin = ({ name, filter, transform }) => ({
+  name,
+  setup(build) {
+    build.onLoad({ filter }, (args) => {
+      const rawFile = getFileAsBuffer(args.path);
+      const css = transform({
+        contents: rawFile,
+        filePath: args.path
+      });
+      if (css instanceof Promise) {
+        return css.then((resolved) => ({
+          exports: { default: resolved },
+          loader: "object"
+        }));
+      }
+      return {
+        exports: {
+          default: css
+        },
+        loader: "object"
+      };
+    });
+  }
+});
+export {
+  createCssLoaderPlugin
+};

package/src/runtime/css-loader.bun.d.ts

@@ -0,0 +1,9 @@
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { CssTransform } from './css-runtime-contract';
+type BunCssLoaderOptions = {
+    name: string;
+    filter: RegExp;
+    transform: CssTransform;
+};
+export declare const createBunCssLoaderPlugin: ({ name, filter, transform }: BunCssLoaderOptions) => EcoBuildPlugin;
+export {};