@ecopages/postcss-processor 0.2.0-alpha.8 → 0.2.1

package/CHANGELOG.md

@@ -4,18 +4,16 @@ All notable changes to `@ecopages/postcss-processor` 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
 
-- Added runtime CSS loader support and a `PostcssProcessor` class so PostCSS processing can be reused outside the plugin DSL.
-- Added esbuild build adapter registration and dependency graph integration to the PostCSS processor plugin.
+- Added reusable runtime CSS loading, a public `PostcssProcessor` class, and build-adapter registration for the plugin.
 
 ### Bug Fixes
 
-- Rebuilt tracked stylesheets from fresh PostCSS plugin instances on non-CSS source changes so Tailwind-style utility generation picks up template edits without stale caches.
-- Applied `transformInput` during direct stylesheet asset processing so Tailwind v4 page CSS keeps injected `@reference` directives and preserves nested BEM selectors in preview/build output.
-- Disabled Tailwind v4 PostCSS optimization in the official plugin preset so preview/build no longer rewrites nested BEM selectors into invalid output.
+- Fixed runtime PostCSS config loading and stylesheet rebuilds for Tailwind-driven template changes.
+- Fixed direct stylesheet processing and preset output so Tailwind v4 preserves injected references and nested BEM selectors.
 
 ### Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/postcss-processor",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.1",
   "description": "Postcss processor, transform string or postcss file to css",
   "keywords": [
     "postcss",
@@ -17,17 +17,17 @@
     "directory": "packages/processors/postcss-processor"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-alpha.8",
-    "@ecopages/file-system": "0.2.0-alpha.8",
-    "@ecopages/logger": "latest",
+    "@ecopages/file-system": "0.2.1",
+    "@ecopages/logger": "^0.2.3",
     "autoprefixer": "^10.4.0",
     "browserslist": "^4.28.1",
-    "cssnano": "^6.0.0",
+    "cssnano": "^7.1.4",
     "postcss": "^8.4.32",
-    "postcss-import": "^15.0.0",
+    "postcss-import": "^16.1.1",
     "postcss-nested": "^7.0.2"
   },
   "peerDependencies": {
+    "@ecopages/core": "0.2.1",
     "@tailwindcss/postcss": ">=4",
     "tailwindcss": ">=3"
   },

package/src/index.d.ts

@@ -1,2 +1,2 @@
-export * from './plugin';
-export * from './postcss-processor';
+export * from './plugin.js';
+export * from './postcss-processor.js';

package/src/index.js

@@ -1,2 +1,2 @@
-export * from "./plugin";
-export * from "./postcss-processor";
+export * from "./plugin.js";
+export * from "./postcss-processor.js";

package/src/plugin.d.ts

@@ -67,11 +67,38 @@ export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPl
     private readonly runtimeCssCache;
     private readonly trackedCssFiles;
     private watchQueue;
+    /**
+     * Maps an imported CSS file path → set of tracked CSS entry files that import it.
+     * Used to resolve which parent entry files need re-processing when a dependency changes.
+     */
+    private readonly cssDependencyMap;
     private getCssFilter;
     private resolveProcessedCssPath;
     private readProcessedCssFromDist;
     private persistProcessedCss;
     private prewarmRuntimeCssCache;
+    /**
+     * Regex to match CSS @import statements and extract the path.
+     * Handles: @import './foo.css'; @import "./foo.css"; @import url('./foo.css');
+     */
+    private static readonly CSS_IMPORT_REGEX;
+    /**
+     * Builds the CSS dependency map by scanning tracked CSS files for @import directives.
+     * Maps each imported file to the set of tracked entry files that import it (directly or transitively).
+     */
+    private buildCssDependencyMap;
+    /**
+     * Extracts resolved absolute paths of CSS files imported via @import in the given CSS content.
+     * Recursively follows imports to capture transitive dependencies.
+     * It skips bare module imports like @import 'tailwindcss'.
+     * It recursively follows imports to capture transitive dependencies.
+     */
+    private extractCssImports;
+    /**
+     * Resolves a changed CSS file to its parent entry file(s) if it is an @import dependency.
+     * Returns an empty array if the file is not an import dependency (i.e., it's an entry file itself).
+     */
+    private resolveEntryFiles;
     private transformCssSync;
     private transformCssAsync;
     matchesFileFilter(filepath: string): boolean;
@@ -83,9 +110,15 @@ export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPl
     constructor(config?: Omit<ProcessorConfig<PostCssProcessorPluginConfig>, 'name' | 'description'>);
     /**
      * Handles CSS file changes during development.
-     * Processes the file and broadcasts a css-update event for hot reloading.
+     * If the file is an @import dependency, re-processes the parent entry file(s) instead.
+     * Broadcasts a css-update event for hot reloading.
      */
     private handleCssChange;
+    /**
+     * Processes a CSS file and broadcasts a css-update event.
+     * Skips broadcast if the processed output hasn't changed.
+     */
+    private processAndBroadcast;
     get buildPlugins(): EcoBuildPlugin[];
     get plugins(): EcoBuildPlugin[];
     /**

package/src/plugin.js

@@ -2,8 +2,8 @@ import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { Processor } from "@ecopages/core/plugins/processor";
 import { Logger } from "@ecopages/logger";
-import { PostCssProcessor } from "./postcss-processor";
-import { createCssLoaderPlugin } from "./runtime/css-loader-plugin";
+import { PostCssProcessor } from "./postcss-processor.js";
+import { createCssLoaderPlugin } from "./runtime/css-loader-plugin.js";
 const logger = new Logger("[@ecopages/postcss-processor]", {
   debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
 });
@@ -17,6 +17,11 @@ class PostCssProcessorPlugin extends Processor {
   runtimeCssCache = /* @__PURE__ */ new Map();
   trackedCssFiles = /* @__PURE__ */ new Set();
   watchQueue = Promise.resolve();
+  /**
+   * Maps an imported CSS file path → set of tracked CSS entry files that import it.
+   * Used to resolve which parent entry files need re-processing when a dependency changes.
+   */
+  cssDependencyMap = /* @__PURE__ */ new Map();
   getCssFilter() {
     return this.options?.filter ?? PostCssProcessorPlugin.DEFAULT_OPTIONS.filter;
   }
@@ -67,6 +72,69 @@ class PostCssProcessorPlugin extends Processor {
       this.runtimeCssCache.set(filePath, processed);
       await this.persistProcessedCss(filePath, processed);
     }
+    this.buildCssDependencyMap();
+  }
+  /**
+   * Regex to match CSS @import statements and extract the path.
+   * Handles: @import './foo.css'; @import "./foo.css"; @import url('./foo.css');
+   */
+  static CSS_IMPORT_REGEX = /@import\s+(?:url\(\s*)?['"]([^'"]+\.css)['"](?:\s*\))?\s*;/gm;
+  /**
+   * Builds the CSS dependency map by scanning tracked CSS files for @import directives.
+   * Maps each imported file to the set of tracked entry files that import it (directly or transitively).
+   */
+  buildCssDependencyMap() {
+    this.cssDependencyMap.clear();
+    for (const entryFile of this.trackedCssFiles) {
+      if (!fileSystem.exists(entryFile)) continue;
+      const rawContents = fileSystem.readFileAsBuffer(entryFile).toString("utf-8");
+      const imports = this.extractCssImports(rawContents, entryFile);
+      for (const importedFile of imports) {
+        if (!this.cssDependencyMap.has(importedFile)) {
+          this.cssDependencyMap.set(importedFile, /* @__PURE__ */ new Set());
+        }
+        this.cssDependencyMap.get(importedFile).add(entryFile);
+      }
+    }
+  }
+  /**
+   * Extracts resolved absolute paths of CSS files imported via @import in the given CSS content.
+   * Recursively follows imports to capture transitive dependencies.
+   * It skips bare module imports like @import 'tailwindcss'.
+   * It recursively follows imports to capture transitive dependencies.
+   */
+  extractCssImports(cssContent, fromFile, visited = /* @__PURE__ */ new Set()) {
+    const dir = path.dirname(fromFile);
+    const imports = [];
+    let match;
+    const regex = new RegExp(PostCssProcessorPlugin.CSS_IMPORT_REGEX.source, "gm");
+    while ((match = regex.exec(cssContent)) !== null) {
+      const importPath = match[1];
+      if (!importPath.startsWith(".") && !importPath.startsWith("/")) {
+        continue;
+      }
+      const resolvedPath = path.resolve(dir, importPath);
+      if (visited.has(resolvedPath)) continue;
+      visited.add(resolvedPath);
+      imports.push(resolvedPath);
+      if (fileSystem.exists(resolvedPath)) {
+        const nestedContent = fileSystem.readFileAsBuffer(resolvedPath).toString("utf-8");
+        const nestedImports = this.extractCssImports(nestedContent, resolvedPath, visited);
+        imports.push(...nestedImports);
+      }
+    }
+    return imports;
+  }
+  /**
+   * Resolves a changed CSS file to its parent entry file(s) if it is an @import dependency.
+   * Returns an empty array if the file is not an import dependency (i.e., it's an entry file itself).
+   */
+  resolveEntryFiles(filePath) {
+    const entries = this.cssDependencyMap.get(filePath);
+    if (!entries || entries.size === 0) {
+      return [];
+    }
+    return Array.from(entries);
   }
   transformCssSync(input) {
     const cached = this.runtimeCssCache.get(input.filePath);
@@ -169,6 +237,8 @@ class PostCssProcessorPlugin extends Processor {
         onCreate: async ({ path: path2, bridge }) => {
           await this.enqueueWatchTask(async () => {
             if (this.matchesFileFilter(path2)) {
+              this.trackedCssFiles.add(path2);
+              this.buildCssDependencyMap();
               await this.handleCssChange(path2, bridge);
               return;
             }
@@ -180,6 +250,8 @@ class PostCssProcessorPlugin extends Processor {
             if (this.matchesFileFilter(path2)) {
               this.runtimeCssCache.delete(path2);
               this.trackedCssFiles.delete(path2);
+              this.cssDependencyMap.delete(path2);
+              this.buildCssDependencyMap();
               return;
             }
             await this.handleDependencyChange(bridge);
@@ -191,9 +263,28 @@ class PostCssProcessorPlugin extends Processor {
   }
   /**
    * Handles CSS file changes during development.
-   * Processes the file and broadcasts a css-update event for hot reloading.
+   * If the file is an @import dependency, re-processes the parent entry file(s) instead.
+   * Broadcasts a css-update event for hot reloading.
    */
   async handleCssChange(filePath, bridge, refreshPlugins = true) {
+    if (!this.context) return;
+    if (!fileSystem.exists(filePath)) return;
+    const entryFiles = this.resolveEntryFiles(filePath);
+    if (entryFiles.length > 0) {
+      logger.debug(`CSS dependency changed: ${filePath}, re-processing ${entryFiles.length} parent(s)`);
+      for (const entryFile of entryFiles) {
+        this.runtimeCssCache.delete(entryFile);
+        await this.processAndBroadcast(entryFile, bridge, refreshPlugins);
+      }
+      return;
+    }
+    await this.processAndBroadcast(filePath, bridge, refreshPlugins);
+  }
+  /**
+   * Processes a CSS file and broadcasts a css-update event.
+   * Skips broadcast if the processed output hasn't changed.
+   */
+  async processAndBroadcast(filePath, bridge, refreshPlugins = true) {
     if (!this.context) return;
     if (!fileSystem.exists(filePath)) return;
     try {
@@ -281,7 +372,10 @@ class PostCssProcessorPlugin extends Processor {
     if (foundConfigPath) {
       try {
         logger.debug(`Loading PostCSS config from: ${foundConfigPath}`);
-        const postcssConfigModule = await import(foundConfigPath);
+        const postcssConfigModule = await import(
+          /* @vite-ignore */
+          foundConfigPath
+        );
         const postcssConfig = postcssConfigModule.default || postcssConfigModule;
         if (postcssConfig && typeof postcssConfig.pluginFactories === "object" && postcssConfig.pluginFactories !== null) {
           loadedPluginFactories = postcssConfig.pluginFactories;

package/src/presets/index.d.ts

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

package/src/presets/index.js

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

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

@@ -1,5 +1,5 @@
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { CssTransform } from './css-runtime-contract';
+import type { CssTransform } from './css-runtime-contract.js';
 type CssLoaderOptions = {
     name: string;
     filter: RegExp;

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

@@ -1,4 +1,4 @@
-import { getFileAsBuffer } from "../postcss-processor";
+import { getFileAsBuffer } from "../postcss-processor.js";
 const createCssLoaderPlugin = ({ name, filter, transform }) => ({
   name,
   setup(build) {

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

@@ -1,5 +1,5 @@
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { CssTransform } from './css-runtime-contract';
+import type { CssTransform } from './css-runtime-contract.js';
 type BunCssLoaderOptions = {
     name: string;
     filter: RegExp;

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

@@ -1,4 +1,4 @@
-import { getFileAsBuffer } from "../postcss-processor";
+import { getFileAsBuffer } from "../postcss-processor.js";
 const createBunCssLoaderPlugin = ({ name, filter, transform }) => ({
   name,
   setup(build) {

package/src/index.ts

@@ -1,2 +0,0 @@
-export * from './plugin';
-export * from './postcss-processor';

package/src/plugin.ts

@@ -1,522 +0,0 @@
-/**
- * PostCssProcessorPlugin
- * @module @ecopages/postcss-processor
- */
-
-import path from 'node:path';
-import type { IClientBridge } from '@ecopages/core';
-import { fileSystem } from '@ecopages/file-system';
-import { Processor, type ProcessorConfig } from '@ecopages/core/plugins/processor';
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import { Logger } from '@ecopages/logger';
-import type postcss from 'postcss';
-import { PostCssProcessor } from './postcss-processor';
-import { createCssLoaderPlugin } from './runtime/css-loader-plugin';
-import type { CssTransformInput } from './runtime/css-runtime-contract';
-
-const logger = new Logger('[@ecopages/postcss-processor]', {
-	debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',
-});
-
-/**
- * Record of PostCSS plugins keyed by name
- */
-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
- */
-export interface PostCssProcessorPluginConfig {
-	/**
-	 * Regex filter to match files to process
-	 */
-	filter?: RegExp;
-	/**
-	 * Function to transform the contents of the file.
-	 * It can be handy to add a custom header or footer to the file.
-	 * Useful for injecting Tailwind v4 `@reference` directives.
-	 * @param contents The contents of the file
-	 * @param filePath The absolute path to the CSS file being processed
-	 * @returns The transformed contents
-	 */
-	transformInput?: (contents: string | Buffer, filePath: string) => string | Promise<string>;
-	/**
-	 * Function to transform the output CSS after PostCSS processing.
-	 * It can be handy to add a custom header or footer to the processed CSS.
-	 * @param css The processed CSS
-	 * @returns The transformed CSS
-	 */
-	transformOutput?: (css: string) => Promise<string> | string;
-	/**
-	 * Custom PostCSS plugins to use instead of the default ones
-	 * @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;
-}
-
-/**
- * PostCssProcessorPlugin
- * A Processor for transforming CSS files.
- */
-export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
-	static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>> = {
-		filter: /\.css$/,
-	};
-
-	private buildContributionsPrepared = false;
-	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;
-	}
-
-	private resolveProcessedCssPath(filePath: string): string | null {
-		if (!this.context) {
-			return null;
-		}
-
-		const relativePath = path.relative(this.context.srcDir, filePath);
-		if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
-			return null;
-		}
-
-		return path.join(this.context.distDir, 'assets', relativePath);
-	}
-
-	private readProcessedCssFromDist(filePath: string): string | null {
-		const outputPath = this.resolveProcessedCssPath(filePath);
-		if (!outputPath || !fileSystem.exists(outputPath)) {
-			return null;
-		}
-
-		return fileSystem.readFileAsBuffer(outputPath).toString('utf-8');
-	}
-
-	private async persistProcessedCss(filePath: string, css: string): Promise<void> {
-		const outputPath = this.resolveProcessedCssPath(filePath);
-		if (!outputPath) {
-			return;
-		}
-
-		fileSystem.ensureDir(path.dirname(outputPath));
-		fileSystem.write(outputPath, css);
-	}
-
-	private async prewarmRuntimeCssCache(): Promise<void> {
-		if (!this.context) {
-			return;
-		}
-
-		const sourceFiles = await fileSystem.glob(['**/*.{css,scss,sass,less}'], {
-			cwd: this.context.srcDir,
-		});
-
-		for (const relativePath of sourceFiles) {
-			const filePath = path.join(this.context.srcDir, relativePath);
-			if (!this.matchesFileFilter(filePath)) {
-				continue;
-			}
-
-			this.trackedCssFiles.add(filePath);
-
-			const rawContents = await fileSystem.readFile(filePath);
-			let transformedInput = rawContents;
-
-			if (this.options?.transformInput) {
-				transformedInput = await this.options.transformInput(rawContents, filePath);
-			}
-
-			const processed = await this.process(transformedInput, filePath);
-			this.runtimeCssCache.set(filePath, processed);
-			await this.persistProcessedCss(filePath, processed);
-		}
-	}
-
-	private transformCssSync(input: CssTransformInput): string {
-		const cached = this.runtimeCssCache.get(input.filePath);
-		if (cached) {
-			return cached;
-		}
-
-		const persisted = this.readProcessedCssFromDist(input.filePath);
-		if (persisted) {
-			this.runtimeCssCache.set(input.filePath, persisted);
-			return persisted;
-		}
-
-		const { contents } = input;
-		return typeof contents === 'string' ? contents : contents.toString('utf-8');
-	}
-
-	private async transformCssAsync(input: CssTransformInput): Promise<string> {
-		const { contents, filePath } = input;
-		let transformed: string = typeof contents === 'string' ? contents : contents.toString('utf-8');
-
-		if (this.options?.transformInput) {
-			const result = this.options.transformInput(contents, filePath);
-			transformed =
-				typeof (result as unknown as Record<string, unknown>).then === 'function'
-					? await (result as Promise<string>)
-					: (result as string);
-		}
-
-		const processed = await this.process(transformed, filePath);
-		this.runtimeCssCache.set(filePath, processed);
-		await this.persistProcessedCss(filePath, processed);
-		return processed;
-	}
-
-	override matchesFileFilter(filepath: string): boolean {
-		const filter = this.options?.filter ?? PostCssProcessorPlugin.DEFAULT_OPTIONS.filter;
-		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,
-		},
-	) {
-		super({
-			name: 'ecopages-postcss-processor',
-			description: 'A Processor for transforming CSS files using PostCSS.',
-			capabilities: [
-				{
-					kind: 'stylesheet',
-					extensions: ['*.{css,scss,sass,less}'],
-				},
-			],
-			watch: {
-				paths: [],
-				extensions: [
-					'.css',
-					'.scss',
-					'.sass',
-					'.less',
-					'.tsx',
-					'.ts',
-					'.jsx',
-					'.js',
-					'.mdx',
-					'.html',
-					'.svelte',
-					'.vue',
-				],
-				onChange: async ({ 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,
-		});
-	}
-
-	/**
-	 * 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, 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) {
-				content = await this.options.transformInput(content, filePath);
-			}
-
-			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);
-
-			bridge.cssUpdate(filePath);
-
-			logger.debug(`Processed CSS: ${filePath}`);
-		} catch (error) {
-			const errorMessage = error instanceof Error ? error.message : String(error);
-			logger.error(`Failed to process CSS: ${filePath}`, errorMessage);
-			bridge.error(errorMessage);
-		}
-	}
-
-	get buildPlugins(): EcoBuildPlugin[] {
-		return [
-			createCssLoaderPlugin({
-				name: 'postcss-processor-build-loader',
-				filter: this.getCssFilter(),
-				transform: this.transformCssAsync.bind(this),
-			}),
-		];
-	}
-
-	get plugins(): EcoBuildPlugin[] {
-		return [
-			createCssLoaderPlugin({
-				name: 'postcss-processor-runtime-loader',
-				filter: this.getCssFilter(),
-				transform: this.transformCssSync.bind(this),
-			}),
-		];
-	}
-
-	/**
-	 * Resolves the configured PostCSS plugin list before config build seals the
-	 * app manifest.
-	 *
-	 * @remarks
-	 * Runtime setup reuses this prepared list and only performs cache prewarming.
-	 */
-	override async prepareBuildContributions(): Promise<void> {
-		if (this.buildContributionsPrepared) {
-			return;
-		}
-
-		await this.collectPostcssPlugins();
-		this.buildContributionsPrepared = true;
-	}
-
-	/**
-	 * Prepares build contributions if not already done and prewarms the runtime CSS cache.
-	 */
-	async setup(): Promise<void> {
-		await this.prepareBuildContributions();
-		await this.prewarmRuntimeCssCache();
-	}
-
-	/**
-	 * Get the PostCSS plugins from the options or a config file.
-	 * Searches for postcss.config.{js,cjs,mjs,ts} in the root directory.
-	 */
-	private async collectPostcssPlugins(): Promise<void> {
-		if (!this.context) {
-			throw new Error('Context must be set');
-		}
-
-		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}`);
-			if (fileSystem.exists(configPath)) {
-				foundConfigPath = configPath;
-				break;
-			}
-		}
-
-		if (foundConfigPath) {
-			try {
-				logger.debug(`Loading PostCSS config from: ${foundConfigPath}`);
-
-				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)) {
-						loadedPlugins = postcssConfig.plugins;
-					} else {
-						loadedPlugins = Object.values(postcssConfig.plugins as PluginsRecord);
-					}
-					logger.debug(`Successfully loaded ${loadedPlugins?.length ?? 0} plugins from config file.`);
-				} else {
-					logger.warn(
-						`PostCSS config file found (${foundConfigPath}), but no valid 'plugins' export detected.`,
-					);
-				}
-			} catch (error: any) {
-				logger.error(`Error loading PostCSS config from ${foundConfigPath}: ${error.message}`, error);
-				loadedPlugins = undefined;
-			}
-		} else {
-			logger.debug('No PostCSS config file found in root directory.');
-		}
-
-		if (loadedPluginFactories) {
-			this.pluginFactories = loadedPluginFactories;
-			this.postcssPlugins = this.materializePluginFactories(loadedPluginFactories);
-		} else if (loadedPlugins) {
-			this.pluginFactories = undefined;
-			this.postcssPlugins = loadedPlugins;
-		} else if (this.options?.pluginFactories || this.options?.plugins) {
-			this.pluginFactories = this.options?.pluginFactories;
-
-			if (this.options?.plugins) {
-				logger.debug('Using PostCSS plugins provided in processor options.');
-				this.postcssPlugins = Object.values(this.options.plugins);
-			} else if (this.options?.pluginFactories) {
-				logger.debug('Using PostCSS plugin factories provided in processor options.');
-				this.postcssPlugins = this.materializePluginFactories(this.options.pluginFactories);
-			}
-		} 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 = [];
-		}
-
-		if (!this.postcssPlugins || this.postcssPlugins.length === 0) {
-			logger.warn('No PostCSS plugins configured or loaded. CSS processing might be minimal.');
-			this.postcssPlugins = [];
-		}
-	}
-
-	/**
-	 * Process CSS content
-	 * @param fileAsString CSS content as string
-	 * @param filePath Optional file path for resolving relative imports
-	 * @returns Processed CSS
-	 */
-	async process(fileAsString: string, filePath?: string): Promise<string> {
-		const input =
-			this.options?.transformInput && filePath
-				? await this.options.transformInput(fileAsString, filePath)
-				: fileAsString;
-
-		return await PostCssProcessor.processStringOrBuffer(input, {
-			filePath,
-			plugins: this.postcssPlugins,
-			transformOutput: this.options?.transformOutput,
-		});
-	}
-
-	processSync(fileAsString: string, filePath?: string): string {
-		const input =
-			this.options?.transformInput && filePath
-				? this.options.transformInput(fileAsString, filePath)
-				: fileAsString;
-
-		if (input instanceof Promise) {
-			throw new Error('transformInput must be synchronous when used with processSync');
-		}
-
-		return PostCssProcessor.processStringOrBufferSync(input, {
-			filePath,
-			plugins: this.postcssPlugins,
-			transformOutput: this.options?.transformOutput,
-		});
-	}
-
-	/**
-	 * Teardown the PostCSS processor.
-	 */
-	async teardown(): Promise<void> {
-		logger.debug('Tearing down PostCSS processor');
-	}
-}
-
-export const postcssProcessorPlugin = (config?: PostCssProcessorPluginConfig): PostCssProcessorPlugin => {
-	return new PostCssProcessorPlugin({
-		options: config,
-	});
-};

package/src/postcss-processor.ts

@@ -1,157 +0,0 @@
-/**
- * This module contains the PostCSS Processor
- * @module
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { Logger } from '@ecopages/logger';
-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>;
-
-const appLogger = new Logger('[@ecopages/postcss-processor]');
-
-export function getFileAsBuffer(path: string): Buffer {
-	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?: PostCssProcessorOptions): postcss.AcceptedPlugin[] => {
-	if (!options || !options.plugins) return [];
-	return Array.isArray(options.plugins) ? options.plugins : Object.values(options.plugins);
-};
-
-/**
- * It processes the given path using PostCSS
- * @param path string
- * @param options {@link PostCssProcessorOptions}
- * @returns string
- *
- * @example
- * ```ts
- * PostCssProcessor.processPath('path/to/file.css').then((processedCss) => {
- *  console.log(processedCss);
- * });\n */
-const processPath: 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 '';
-		});
-};
-
-/**
- * It processes the given string or buffer using PostCSS
- * @param contents string | Buffer
- * @param options {@link PostCssProcessorOptions}
- * @returns string
- *
- * @example
- * ```ts
- * const css = `body { @apply bg-blue-500; }`;
- *
- * PostCssProcessor.processString(css).then((processedCss) => {
- * console.log(processedCss);
- * });
- * ```
- */
-const processStringOrBuffer: 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 '';
-		});
-};
-
-export type ProcessStringOrBufferSync = (contents: string | Buffer, options?: PostCssProcessorOptions) => string;
-
-const processStringOrBufferSync: 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 as Error).message);
-		return '';
-	}
-};
-
-/**
- * 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 const PostCssProcessor: {
-	processPath: ProcessPath;
-	processStringOrBuffer: ProcessStringOrBuffer;
-	processStringOrBufferSync: ProcessStringOrBufferSync;
-} = {
-	processPath,
-	processStringOrBuffer,
-	processStringOrBufferSync,
-};

package/src/presets/index.ts

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

package/src/presets/tailwind-v3.ts

@@ -1,72 +0,0 @@
-/**
- * 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 autoprefixer from 'autoprefixer';
-import browserslist from 'browserslist';
-import cssnano from 'cssnano';
-import type postcss from 'postcss';
-import postcssImport from 'postcss-import';
-import tailwindcss from 'tailwindcss';
-import tailwindcssNesting from 'tailwindcss/nesting/index.js';
-import type { PluginFactoryRecord, PostCssProcessorPluginConfig } from '../plugin.ts';
-
-type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
-
-/**
- * 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 function tailwindV3Preset(): PostCssProcessorPluginConfig {
-	// Check if browserslist config exists
-	const browserslistConfig = browserslist.loadConfig({ path: process.cwd() });
-	const autoprefixerOptions = browserslistConfig
-		? {}
-		: {
-				overrideBrowserslist: ['>0.3%', 'not ie 11', 'not dead', 'not op_mini all'],
-			};
-
-	const pluginFactories: PluginFactoryRecord = {
-		'postcss-import': () => postcssImport(),
-		'tailwindcss/nesting': () => tailwindcssNesting(),
-		tailwindcss: () => tailwindcss(),
-		autoprefixer: () => autoprefixer(autoprefixerOptions),
-		cssnano: () => cssnano(),
-	};
-
-	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.ts

@@ -1,122 +0,0 @@
-/**
- * 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 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';
-import type { PluginFactoryRecord, PostCssProcessorPluginConfig } from '../plugin.ts';
-
-/**
- * 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 function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProcessorPluginConfig {
-	const { referencePath } = options;
-
-	// Check if browserslist config exists
-	const browserslistConfig = browserslist.loadConfig({ path: process.cwd() });
-	const autoprefixerOptions = browserslistConfig
-		? {}
-		: {
-				overrideBrowserslist: ['>0.3%', 'not ie 11', 'not dead', 'not op_mini all'],
-			};
-
-	const pluginFactories: PluginFactoryRecord = {
-		'postcss-import': () => postcssImport(),
-		'postcss-nested': () => postcssNested(),
-		'@tailwindcss/postcss': () => tailwindcss({ optimize: false }),
-		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: string | Buffer, filePath: string): Promise<string> => {
-			const css = contents instanceof Buffer ? contents.toString('utf-8') : (contents as string);
-			const normalizedFilePath = path.resolve(filePath);
-			const normalizedReferencePath = path.resolve(referencePath);
-
-			/** Skip transformation for the main tailwind entry file */
-			if (normalizedFilePath === normalizedReferencePath) {
-				return css;
-			}
-
-			/** Skip if file already has an @reference directive */
-			if (/^\s*@reference\s+/m.test(css)) {
-				return css;
-			}
-
-			const relativePath = path.relative(path.dirname(filePath), referencePath);
-
-			/** Skip if file already imports the referencePath */
-			if (css.includes(`@import '${relativePath}'`) || css.includes(`@import "${relativePath}"`)) {
-				return css;
-			}
-
-			/**
-			 * Replace `@import 'tailwindcss'` with an import to the referencePath.
-			 * This ensures custom theme variables are available for @apply directives.
-			 */
-			const tailwindImportPattern = /^@import\s+['"]tailwindcss(?:\/[^'"]*)?['"];?\s*$/m;
-			if (tailwindImportPattern.test(css)) {
-				return css.replace(tailwindImportPattern, `@import '${relativePath}';`);
-			}
-
-			/** If file uses @apply but has no tailwind import, add @reference */
-			if (css.includes('@apply')) {
-				return `@reference "${relativePath}";\n\n${css}`;
-			}
-
-			return css;
-		},
-	};
-}

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

@@ -1,37 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-
-import { getFileAsBuffer } from '../postcss-processor';
-import type { CssTransform } from './css-runtime-contract';
-
-type CssLoaderOptions = {
-	name: string;
-	filter: RegExp;
-	transform: CssTransform;
-};
-
-export const createCssLoaderPlugin = ({ name, filter, transform }: CssLoaderOptions): EcoBuildPlugin => ({
-	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' as const,
-				}));
-			}
-
-			return {
-				exports: {
-					default: css as string,
-				},
-				loader: 'object' as const,
-			};
-		});
-	},
-});

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

@@ -1,30 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-
-import { getFileAsBuffer } from '../postcss-processor';
-import type { CssTransform } from './css-runtime-contract';
-
-type BunCssLoaderOptions = {
-	name: string;
-	filter: RegExp;
-	transform: CssTransform;
-};
-
-export const createBunCssLoaderPlugin = ({ name, filter, transform }: BunCssLoaderOptions): EcoBuildPlugin => ({
-	name,
-	setup(build) {
-		build.onLoad({ filter }, async (args) => {
-			const rawFile = await getFileAsBuffer(args.path);
-			const css = await transform({
-				contents: rawFile,
-				filePath: args.path,
-			});
-
-			return {
-				exports: {
-					default: css,
-				},
-				loader: 'object',
-			};
-		});
-	},
-});

package/src/runtime/css-runtime-contract.ts

@@ -1,6 +0,0 @@
-export type CssTransformInput = {
-	contents: string | Buffer;
-	filePath: string;
-};
-
-export type CssTransform = (input: CssTransformInput) => string | Promise<string>;