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

package/CHANGELOG.md

@@ -6,21 +6,17 @@ All notable changes to `@ecopages/postcss-processor` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Bug Fixes
-
-- Rebuilt tracked stylesheets from fresh PostCSS plugin instances on non-CSS source changes so Tailwind utility generation updates without stale caches or forced reloads.
-
 ### Features
 
-- **Runtime CSS loaders** — Added `css-loader-plugin.ts`, `css-loader.bun.ts`, and `css-runtime-contract.ts` to support runtime CSS loading. CSS is now cached at runtime to avoid redundant processing during HMR (`cbaafea4`, `e7653c9b`).
-- **`PostcssProcessor` class** — New `postcss-processor.ts` exposes a programmatic API for the processor separate from the plugin DSL.
+- 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.
 
-### Refactoring
+### Bug Fixes
 
-- `plugin.ts` significantly overhauled to integrate with the new build adapter and support build dependency graph registration (`e7653c9b`).
-- Test suite updated for esbuild adapter and Node runtime compatibility (`31a44458`).
-- Removed unused `@types/postcss` dev dependency.
+- 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.
 
 ### Tests
 
-- Updated `plugin.test.ts`, `postcss-processor.test.ts`, and `presets.test.ts` for new plugin contract.
+- Added processor and preset coverage for the runtime CSS loader and build adapter flow.

package/README.md

@@ -1,56 +1,32 @@
-# PostCSS Processor
+# @ecopages/postcss-processor
 
-This module provides a PostCSS processor plugin for Ecopages and utility functions for processing CSS files and strings using PostCSS. It includes built-in presets for Tailwind CSS (v3 and v4).
+PostCSS processing pipeline for Ecopages. It provides a processor plugin that seamlessly integrates PostCSS into the Ecopages build system, and includes built-in presets for Tailwind CSS (v3 and v4).
 
 ## Features
 
-- **Ecopages Processor Plugin**: Seamless integration with Ecopages build system.
-- **Tailwind Presets**: Ready-to-use configurations for Tailwind CSS v3 and v4.
-- **Automatic Configuration**: Detects `postcss.config.{js,ts,etc}` automatically.
-- **Standalone Usage**: Process CSS files or strings directly.
-- **Bun Loader**: Automatically registers a Bun loader for importing CSS in TS/JS files.
+- **Ecopages Processor Plugin**: Hook right into the build pipeline.
+- **Tailwind Presets**: Pre-configured pipelines for Tailwind CSS v3 and v4.
+- **Automatic Configuration**: Detects existing `postcss.config.{js,ts,etc}`.
+- **Bun Loader**: Registers a Bun loader for importing CSS in TS/JS files.
 
-## Install
+## Installation
 
 ```bash
 bunx jsr add @ecopages/postcss-processor
 ```
 
-## Usage with Ecopages
+## Usage
 
-Integrate the processor into your `eco.config.ts` using one of the available presets.
-
-### Tailwind v3 Preset
-
-Includes `tailwindcss`, `autoprefixer`, `postcss-import`, `cssnano`.
-
-```bash
-bun add -D tailwindcss@3.4.19
-```
-
-```typescript
-// eco.config.ts
-import { ConfigBuilder } from '@ecopages/core';
-import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
-
-const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
-
-export default config;
-```
+Integrate the processor into your `eco.config.ts` using a preset.
 
 ### Tailwind v4 Preset (Recommended)
 
-Includes `@tailwindcss/postcss`, `autoprefixer`, `postcss-nested`, `cssnano`, and handles `@reference` injection for `@apply`.
-
-```bash
-bun add -D @tailwindcss/postcss tailwindcss
-```
+Requires `@tailwindcss/postcss` and `tailwindcss` to be installed.
 
 ```typescript
 // eco.config.ts
 import path from 'node:path';
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
 import { tailwindV4Preset } from '@ecopages/postcss-processor/presets/tailwind-v4';
 
@@ -58,7 +34,7 @@ const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin(
 			tailwindV4Preset({
-				referencePath: path.resolve(import.meta.dir, 'src/styles/app.css'),
+				referencePath: path.resolve(import.meta.dirname, 'src/styles/app.css'),
 			}),
 		),
 	])
@@ -67,53 +43,41 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-### Browser Support
-
-By default, the presets target a broad range of modern browsers (`>0.3%, not ie 11, not dead, not op_mini all`).
-
-To override this, add a `browserslist` configuration to your `package.json` or create a `.browserslistrc` file in your project root. The processor will automatically detect and use your custom configuration.
-
-### Custom Configuration
-
-You can also use a standard `postcss.config.js` file or pass plugins manually.
-
-**Using `postcss.config.js`:**
-Create the file in your root, and simply add `postcssProcessorPlugin()` to your config without arguments.
+### Tailwind v3 Preset
 
-**Manual Configuration:**
+Requires `tailwindcss@3`, `autoprefixer`, `postcss-import`, and `cssnano` to be installed.
 
 ```typescript
+// eco.config.ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import myPlugin from 'postcss-my-plugin';
+import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
+
+const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
 
-postcssProcessorPlugin({
-	plugins: {
-		'my-plugin': myPlugin(),
-	},
-});
+export default config;
 ```
 
-**Advanced Configuration:**
+## Custom Configuration
 
-For advanced use cases, use transformation hooks to modify CSS before or after processing:
+To use your own `postcss.config.js`, simply call `postcssProcessorPlugin()` without arguments.
+
+You can also pass raw plugins or transformation hooks manually:
 
 ```typescript
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+import myPlugin from 'postcss-my-plugin';
 
 const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin({
-			// Define a filter for files to process (defaults to /\.css$/)
 			filter: /\.css$/,
-			// Provide a function to transform input before processing
-			transformInput: async (css) => `/* My Custom Header */\n${css}`,
-			// Provide a function to transform output after processing
-			transformOutput: async (css) => css.replace('blue', 'red'),
-			// Explicitly provide plugins (overrides defaults)
 			plugins: {
-				/* custom plugins */
+				'my-plugin': myPlugin(),
 			},
+			transformInput: async (css) => `/* Header */\n${css}`,
+			transformOutput: async (css) => css.replace('blue', 'red'),
 		}),
 	])
 	.build();
@@ -121,9 +85,9 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-## Standalone Usage
+## Standalone Processing
 
-You can use the underlying processor functions directly:
+You can bypass Ecopages entirely and use the processor utilities directly:
 
 ```typescript
 import { PostCssProcessor } from '@ecopages/postcss-processor';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/postcss-processor",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.8",
   "description": "Postcss processor, transform string or postcss file to css",
   "keywords": [
     "postcss",
@@ -17,8 +17,8 @@
     "directory": "packages/processors/postcss-processor"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-alpha.5",
-    "@ecopages/file-system": "0.2.0-alpha.5",
+    "@ecopages/core": "0.2.0-alpha.8",
+    "@ecopages/file-system": "0.2.0-alpha.8",
     "@ecopages/logger": "latest",
     "autoprefixer": "^10.4.0",
     "browserslist": "^4.28.1",

package/src/plugin.d.ts

@@ -61,6 +61,7 @@ export interface PostCssProcessorPluginConfig {
  */
 export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
     static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>>;
+    private buildContributionsPrepared;
     private postcssPlugins;
     private pluginFactories?;
     private readonly runtimeCssCache;
@@ -88,7 +89,15 @@ export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPl
     get buildPlugins(): EcoBuildPlugin[];
     get plugins(): EcoBuildPlugin[];
     /**
-     * Setup the PostCSS processor.
+     * 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.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Prepares build contributions if not already done and prewarms the runtime CSS cache.
      */
     setup(): Promise<void>;
     /**

package/src/plugin.js

@@ -11,6 +11,7 @@ class PostCssProcessorPlugin extends Processor {
   static DEFAULT_OPTIONS = {
     filter: /\.css$/
   };
+  buildContributionsPrepared = false;
   postcssPlugins = [];
   pluginFactories;
   runtimeCssCache = /* @__PURE__ */ new Map();
@@ -238,10 +239,24 @@ class PostCssProcessorPlugin extends Processor {
     ];
   }
   /**
-   * Setup the PostCSS processor.
+   * 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.
    */
-  async setup() {
+  async prepareBuildContributions() {
+    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() {
+    await this.prepareBuildContributions();
     await this.prewarmRuntimeCssCache();
   }
   /**
@@ -296,14 +311,15 @@ class PostCssProcessorPlugin extends Processor {
     } else if (loadedPlugins) {
       this.pluginFactories = void 0;
       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 = void 0;
-      this.postcssPlugins = Object.values(this.options.plugins);
+    } 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."
@@ -323,14 +339,19 @@ class PostCssProcessorPlugin extends Processor {
    * @returns Processed CSS
    */
   async process(fileAsString, filePath) {
-    return await PostCssProcessor.processStringOrBuffer(fileAsString, {
+    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, filePath) {
-    return PostCssProcessor.processStringOrBufferSync(fileAsString, {
+    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

package/src/plugin.ts

@@ -80,6 +80,7 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 		filter: /\.css$/,
 	};
 
+	private buildContributionsPrepared = false;
 	private postcssPlugins: postcss.AcceptedPlugin[] = [];
 	private pluginFactories?: PluginFactoryRecord;
 	private readonly runtimeCssCache = new Map<string, string>();
@@ -360,10 +361,26 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 	}
 
 	/**
-	 * Setup the PostCSS processor.
+	 * 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.
 	 */
-	async setup(): Promise<void> {
+	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();
 	}
 
@@ -429,14 +446,16 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 		} 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 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(), ' +
@@ -459,7 +478,12 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 	 * @returns Processed CSS
 	 */
 	async process(fileAsString: string, filePath?: string): Promise<string> {
-		return await PostCssProcessor.processStringOrBuffer(fileAsString, {
+		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,
@@ -467,7 +491,16 @@ export class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConf
 	}
 
 	processSync(fileAsString: string, filePath?: string): string {
-		return PostCssProcessor.processStringOrBufferSync(fileAsString, {
+		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,

package/src/presets/tailwind-v4.js

@@ -14,7 +14,7 @@ function tailwindV4Preset(options) {
   const pluginFactories = {
     "postcss-import": () => postcssImport(),
     "postcss-nested": () => postcssNested(),
-    "@tailwindcss/postcss": () => tailwindcss(),
+    "@tailwindcss/postcss": () => tailwindcss({ optimize: false }),
     autoprefixer: () => autoprefixer(autoprefixerOptions),
     cssnano: () => cssnano()
   };

package/src/presets/tailwind-v4.ts

@@ -68,7 +68,7 @@ export function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProce
 	const pluginFactories: PluginFactoryRecord = {
 		'postcss-import': () => postcssImport(),
 		'postcss-nested': () => postcssNested(),
-		'@tailwindcss/postcss': () => tailwindcss(),
+		'@tailwindcss/postcss': () => tailwindcss({ optimize: false }),
 		autoprefixer: () => autoprefixer(autoprefixerOptions),
 		cssnano: () => cssnano(),
 	};