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

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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
+
+### 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.
+
+### Refactoring
+
+- `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.
+
+### Tests
+
+- Updated `plugin.test.ts`, `postcss-processor.test.ts`, and `presets.test.ts` for new plugin contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/postcss-processor",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "description": "Postcss processor, transform string or postcss file to css",
   "keywords": [
     "postcss",
@@ -8,24 +8,17 @@
     "css"
   ],
   "license": "MIT",
-  "main": "./src/postcss-processor.ts",
+  "main": "./src/postcss-processor.js",
   "type": "module",
-  "types": "./src/postcss-processor.ts",
-  "files": [
-    "src"
-  ],
+  "types": "./src/postcss-processor.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/ecopages/ecopages.git",
     "directory": "packages/processors/postcss-processor"
   },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "release:jsr": "bunx jsr publish"
-  },
   "dependencies": {
-    "@ecopages/core": "workspace:*",
-    "@ecopages/file-system": "workspace:*",
+    "@ecopages/core": "0.2.0-alpha.2",
+    "@ecopages/file-system": "0.2.0-alpha.2",
     "@ecopages/logger": "latest",
     "autoprefixer": "^10.4.0",
     "browserslist": "^4.28.1",
@@ -46,37 +39,50 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/bun": "latest",
-    "@types/postcss-import": "^14",
-    "postcss-simple-vars": "^7.0.1",
-    "tailwindcss": "^3.4.19"
-  },
   "exports": {
     ".": {
-      "default": "./src/index.ts",
-      "types": "./src/index.ts"
+      "default": "./src/index.js",
+      "types": "./src/index.d.ts"
     },
     "./postcss-processor": {
-      "default": "./src/postcss-processor.ts",
-      "types": "./src/postcss-processor.ts"
+      "default": "./src/postcss-processor.js",
+      "types": "./src/postcss-processor.d.ts"
     },
     "./plugin": {
-      "default": "./src/plugin.ts",
-      "types": "./src/plugin.ts"
+      "default": "./src/plugin.js",
+      "types": "./src/plugin.d.ts"
     },
     "./presets": {
-      "default": "./src/presets/index.ts",
-      "types": "./src/presets/index.ts"
+      "default": "./src/presets/index.js",
+      "types": "./src/presets/index.d.ts"
     },
     "./presets/tailwind-v3": {
-      "default": "./src/presets/tailwind-v3.ts",
-      "types": "./src/presets/tailwind-v3.ts"
+      "default": "./src/presets/tailwind-v3.js",
+      "types": "./src/presets/tailwind-v3.d.ts"
     },
     "./presets/tailwind-v4": {
-      "default": "./src/presets/tailwind-v4.ts",
-      "types": "./src/presets/tailwind-v4.ts"
+      "default": "./src/presets/tailwind-v4.js",
+      "types": "./src/presets/tailwind-v4.d.ts"
+    },
+    "./postcss-processor.ts": {
+      "default": "./src/postcss-processor.js",
+      "types": "./src/postcss-processor.d.ts"
+    },
+    "./plugin.ts": {
+      "default": "./src/plugin.js",
+      "types": "./src/plugin.d.ts"
+    },
+    "./presets.ts": {
+      "default": "./src/presets/index.js",
+      "types": "./src/presets/index.d.ts"
+    },
+    "./presets/tailwind-v3.ts": {
+      "default": "./src/presets/tailwind-v3.js",
+      "types": "./src/presets/tailwind-v3.d.ts"
+    },
+    "./presets/tailwind-v4.ts": {
+      "default": "./src/presets/tailwind-v4.js",
+      "types": "./src/presets/tailwind-v4.d.ts"
     }
   }
-}
+}

package/src/index.d.ts

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

package/src/index.js

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

package/src/plugin.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PostCssProcessorPlugin
+ * @module @ecopages/postcss-processor
+ */
+import { Processor, type ProcessorConfig } from '@ecopages/core/plugins/processor';
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type postcss from 'postcss';
+/**
+ * Record of PostCSS plugins keyed by name
+ */
+export type PluginsRecord = 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;
+}
+/**
+ * PostCssProcessorPlugin
+ * A Processor for transforming CSS files.
+ */
+export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
+    static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>>;
+    private postcssPlugins;
+    private readonly runtimeCssCache;
+    private getCssFilter;
+    private resolveProcessedCssPath;
+    private readProcessedCssFromDist;
+    private persistProcessedCss;
+    private prewarmRuntimeCssCache;
+    private transformCssSync;
+    private transformCssAsync;
+    matchesFileFilter(filepath: string): boolean;
+    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.
+     */
+    private handleCssChange;
+    get buildPlugins(): EcoBuildPlugin[];
+    get plugins(): EcoBuildPlugin[];
+    /**
+     * Setup the PostCSS processor.
+     */
+    setup(): Promise<void>;
+    /**
+     * Get the PostCSS plugins from the options or a config file.
+     * Searches for postcss.config.{js,cjs,mjs,ts} in the root directory.
+     */
+    private collectPostcssPlugins;
+    /**
+     * Process CSS content
+     * @param fileAsString CSS content as string
+     * @param filePath Optional file path for resolving relative imports
+     * @returns Processed CSS
+     */
+    process(fileAsString: string, filePath?: string): Promise<string>;
+    processSync(fileAsString: string, filePath?: string): string;
+    /**
+     * Teardown the PostCSS processor.
+     */
+    teardown(): Promise<void>;
+}
+export declare const postcssProcessorPlugin: (config?: PostCssProcessorPluginConfig) => PostCssProcessorPlugin;

package/src/plugin.js

@@ -0,0 +1,257 @@
+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";
+const logger = new Logger("[@ecopages/postcss-processor]", {
+  debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
+});
+class PostCssProcessorPlugin extends Processor {
+  static DEFAULT_OPTIONS = {
+    filter: /\.css$/
+  };
+  postcssPlugins = [];
+  runtimeCssCache = /* @__PURE__ */ new Map();
+  getCssFilter() {
+    return this.options?.filter ?? PostCssProcessorPlugin.DEFAULT_OPTIONS.filter;
+  }
+  resolveProcessedCssPath(filePath) {
+    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);
+  }
+  readProcessedCssFromDist(filePath) {
+    const outputPath = this.resolveProcessedCssPath(filePath);
+    if (!outputPath || !fileSystem.exists(outputPath)) {
+      return null;
+    }
+    return fileSystem.readFileAsBuffer(outputPath).toString("utf-8");
+  }
+  async persistProcessedCss(filePath, css) {
+    const outputPath = this.resolveProcessedCssPath(filePath);
+    if (!outputPath) {
+      return;
+    }
+    fileSystem.ensureDir(path.dirname(outputPath));
+    fileSystem.write(outputPath, css);
+  }
+  async prewarmRuntimeCssCache() {
+    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;
+      }
+      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);
+    }
+  }
+  transformCssSync(input) {
+    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");
+  }
+  async transformCssAsync(input) {
+    const { contents, filePath } = input;
+    let transformed = typeof contents === "string" ? contents : contents.toString("utf-8");
+    if (this.options?.transformInput) {
+      const result = this.options.transformInput(contents, filePath);
+      transformed = typeof result.then === "function" ? await result : result;
+    }
+    const processed = await this.process(transformed, filePath);
+    this.runtimeCssCache.set(filePath, processed);
+    await this.persistProcessedCss(filePath, processed);
+    return processed;
+  }
+  matchesFileFilter(filepath) {
+    const filter = this.options?.filter ?? PostCssProcessorPlugin.DEFAULT_OPTIONS.filter;
+    return filter.test(filepath);
+  }
+  constructor(config = {
+    options: PostCssProcessorPlugin.DEFAULT_OPTIONS
+  }) {
+    super({
+      name: "ecopages-postcss-processor",
+      description: "A Processor for transforming CSS files using PostCSS.",
+      capabilities: [
+        {
+          kind: "stylesheet",
+          extensions: ["*.css"]
+        }
+      ],
+      watch: {
+        paths: [],
+        extensions: [".css", ".scss", ".sass", ".less"],
+        onChange: async ({ path: path2, bridge }) => {
+          await this.handleCssChange(path2, bridge);
+        }
+      },
+      ...config
+    });
+  }
+  /**
+   * Handles CSS file changes during development.
+   * Processes the file and broadcasts a css-update event for hot reloading.
+   */
+  async handleCssChange(filePath, bridge) {
+    if (!this.context) return;
+    try {
+      let content = await fileSystem.readFile(filePath);
+      if (this.options?.transformInput) {
+        content = await this.options.transformInput(content, filePath);
+      }
+      const processed = await this.process(content, filePath);
+      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() {
+    return [
+      createCssLoaderPlugin({
+        name: "postcss-processor-build-loader",
+        filter: this.getCssFilter(),
+        transform: this.transformCssAsync.bind(this)
+      })
+    ];
+  }
+  get plugins() {
+    return [
+      createCssLoaderPlugin({
+        name: "postcss-processor-runtime-loader",
+        filter: this.getCssFilter(),
+        transform: this.transformCssSync.bind(this)
+      })
+    ];
+  }
+  /**
+   * Setup the PostCSS processor.
+   */
+  async setup() {
+    await this.collectPostcssPlugins();
+    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.
+   */
+  async collectPostcssPlugins() {
+    if (!this.context) {
+      throw new Error("Context must be set");
+    }
+    const configExtensions = ["js", "cjs", "mjs", "ts"];
+    let foundConfigPath;
+    let loadedPlugins;
+    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.plugins === "object" && postcssConfig.plugins !== null) {
+          if (Array.isArray(postcssConfig.plugins)) {
+            loadedPlugins = postcssConfig.plugins;
+          } else {
+            loadedPlugins = Object.values(postcssConfig.plugins);
+          }
+          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) {
+        logger.error(`Error loading PostCSS config from ${foundConfigPath}: ${error.message}`, error);
+        loadedPlugins = void 0;
+      }
+    } else {
+      logger.debug("No PostCSS config file found in root directory.");
+    }
+    if (loadedPlugins) {
+      this.postcssPlugins = loadedPlugins;
+    } else if (this.options?.plugins) {
+      logger.debug("Using PostCSS plugins provided in processor options.");
+      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.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, filePath) {
+    return await PostCssProcessor.processStringOrBuffer(fileAsString, {
+      filePath,
+      plugins: this.postcssPlugins,
+      transformOutput: this.options?.transformOutput
+    });
+  }
+  processSync(fileAsString, filePath) {
+    return PostCssProcessor.processStringOrBufferSync(fileAsString, {
+      filePath,
+      plugins: this.postcssPlugins,
+      transformOutput: this.options?.transformOutput
+    });
+  }
+  /**
+   * Teardown the PostCSS processor.
+   */
+  async teardown() {
+    logger.debug("Tearing down PostCSS processor");
+  }
+}
+const postcssProcessorPlugin = (config) => {
+  return new PostCssProcessorPlugin({
+    options: config
+  });
+};
+export {
+  PostCssProcessorPlugin,
+  postcssProcessorPlugin
+};

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,32 @@
+/**
+ * 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
+ *
+ * @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,23 @@
+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 plugins = {
+    "postcss-import": postcssImport(),
+    "tailwindcss/nesting": tailwindcssNesting(),
+    tailwindcss: tailwindcss(),
+    autoprefixer: autoprefixer(autoprefixerOptions),
+    cssnano: cssnano()
+  };
+  return { plugins };
+}
+export {
+  tailwindV3Preset
+};

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

@@ -0,0 +1,45 @@
+/**
+ * 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
+ *
+ * @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,51 @@
+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"]
+  };
+  return {
+    plugins: {
+      "postcss-import": postcssImport(),
+      "postcss-nested": postcssNested(),
+      "@tailwindcss/postcss": tailwindcss(),
+      autoprefixer: autoprefixer(autoprefixerOptions),
+      cssnano: cssnano()
+    },
+    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/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 {};

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

@@ -0,0 +1,22 @@
+import { getFileAsBuffer } from "../postcss-processor";
+const createBunCssLoaderPlugin = ({ name, filter, transform }) => ({
+  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"
+      };
+    });
+  }
+});
+export {
+  createBunCssLoaderPlugin
+};

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

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

package/src/test/css/base.css

@@ -1,3 +0,0 @@
-.base {
-	color: red;
-}

package/src/test/css/correct.css

@@ -1,3 +0,0 @@
-.test {
-	@apply bg-red-500;
-}

package/src/test/css/error.css

@@ -1,3 +0,0 @@
-.test {
-	@apply bg-reds-500;
-}

package/src/test/css/external-plugins.css

@@ -1,13 +0,0 @@
-$dir: top;
-$blue: #056ef0;
-$column: 200px;
-
-.menu_link {
-	background: $blue;
-	width: $column;
-}
-
-.menu {
-	width: calc(4 * $column);
-	margin-$(dir): 10px;
-}

package/src/test/css/import.css

@@ -1,4 +0,0 @@
-@import 'base.css';
-.main {
-	background: blue;
-}

package/src/test/plugin.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, test, afterAll, beforeAll, vi } from 'vitest';
-import path from 'node:path';
-import fs from 'node:fs';
-import { PostCssProcessorPlugin } from '../plugin';
-import type { ClientBridge } from '@ecopages/core/adapters/bun/client-bridge';
-import { ConfigBuilder } from '@ecopages/core/config-builder';
-
-const TMP_DIR = path.join(__dirname, 'tmp_test_hmr');
-const SRC_DIR = path.join(TMP_DIR, 'src');
-const DIST_DIR = path.join(TMP_DIR, 'dist');
-
-describe('PostCssProcessorPlugin HMR', () => {
-	beforeAll(() => {
-		if (fs.existsSync(TMP_DIR)) {
-			fs.rmSync(TMP_DIR, { recursive: true, force: true });
-		}
-		fs.mkdirSync(SRC_DIR, { recursive: true });
-		fs.mkdirSync(DIST_DIR, { recursive: true });
-	});
-
-	afterAll(() => {
-		fs.rmSync(TMP_DIR, { recursive: true, force: true });
-	});
-
-	test('handleCssChange should apply transformInput', async () => {
-		const cssFile = path.join(SRC_DIR, 'style.css');
-		fs.writeFileSync(cssFile, '.foo { color: red; }');
-
-		const plugin = new PostCssProcessorPlugin({
-			options: {
-				filter: /\.css$/,
-				transformInput: async (content) => {
-					return `/* prefix */\n${content}`;
-				},
-			},
-		});
-
-		const config = await new ConfigBuilder()
-			.setRootDir(TMP_DIR)
-			.setSrcDir('src')
-			.setDistDir('dist')
-			.setBaseUrl('http://localhost:3000')
-			.build();
-
-		plugin.setContext(config);
-
-		const Bridge = {
-			cssUpdate: () => {},
-			error: (msg: string) => {
-				throw new Error(msg);
-			},
-			reload: () => {},
-		} as unknown as ClientBridge;
-
-		const bridgeSpy = vi.spyOn(Bridge, 'cssUpdate');
-
-		const watchConfig = plugin.getWatchConfig();
-		if (watchConfig && watchConfig.onChange) {
-			await watchConfig.onChange({ path: cssFile, bridge: Bridge });
-		} else {
-			throw new Error('Plugin does not have watch handler');
-		}
-
-		const outputFile = path.join(DIST_DIR, 'assets', 'style.css');
-		expect(fs.existsSync(outputFile)).toBe(true);
-
-		const outputContent = fs.readFileSync(outputFile, 'utf-8');
-		expect(outputContent).toContain('/* prefix */');
-		expect(outputContent).toContain('.foo { color: red; }');
-
-		expect(bridgeSpy).toHaveBeenCalled();
-		expect(bridgeSpy).toHaveBeenCalledWith(cssFile);
-	});
-});

package/src/test/postcss-processor.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import path from 'node:path';
-import postCssSimpleVars from 'postcss-simple-vars';
-import { PostCssProcessor } from '../postcss-processor';
-import { tailwindV3Preset } from '../presets/tailwind-v3';
-
-describe('PostCssProcessor', () => {
-	test('processPath should return the processed CSS', async () => {
-		const filePath = path.resolve(__dirname, './css/correct.css');
-		const expected = '.test{--tw-bg-opacity:1;background-color:rgb(239 68 68/var(--tw-bg-opacity,1))}';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processPath(filePath, { plugins: plugins ? Object.values(plugins) : [] });
-		expect(result).toEqual(expected);
-	});
-
-	test('processPath should return an empty string when an error occurs during css conversion', async () => {
-		const filePath = path.resolve(__dirname, './css/error.css');
-		const expected = '';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processPath(filePath, { plugins: plugins ? Object.values(plugins) : [] });
-		expect(result).toEqual(expected);
-	});
-
-	test('processPath should throw when the file does not exist', async () => {
-		const filePath = 'fake-path.css';
-		await expect(PostCssProcessor.processPath(filePath)).rejects.toThrow();
-	});
-
-	test('processPath should use the custom plugins', async () => {
-		const filePath = path.resolve(__dirname, './css/external-plugins.css');
-		const expected = '.menu_link{background:#056ef0;width:200px}.menu{margin-top:10px;width:800px}';
-		const result = await PostCssProcessor.processPath(filePath, {
-			plugins: [...Object.values(tailwindV3Preset().plugins ?? {}), postCssSimpleVars()],
-		});
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should return the processed CSS', async () => {
-		const string = 'body { @apply bg-white; }';
-		const expected = 'body{--tw-bg-opacity:1;background-color:rgb(255 255 255/var(--tw-bg-opacity,1))}';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processStringOrBuffer(string, {
-			plugins: plugins ? Object.values(plugins) : [],
-		});
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should return an empty string when an error occurs during css conversion', async () => {
-		const string = 'body { @apply bg-whites; }';
-		const expected = '';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processStringOrBuffer(string, {
-			plugins: plugins ? Object.values(plugins) : [],
-		});
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should return an empty string when the input is empty', async () => {
-		const string = '';
-		const expected = '';
-		const result = await PostCssProcessor.processStringOrBuffer(string);
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should use the custom plugins', async () => {
-		const string = '$blue: #056ef0; body { background: $blue; }';
-		const expected = 'body{background:#056ef0}';
-		const result = await PostCssProcessor.processStringOrBuffer(string, {
-			plugins: [...Object.values(tailwindV3Preset().plugins ?? {}), postCssSimpleVars()],
-		});
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should use the transformOutput', async () => {
-		const string = 'body { background: #056ef0; }';
-		const expected = '@reference "../app.css";\nbody{background:#056ef0}';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processStringOrBuffer(string, {
-			plugins: plugins?.cssnano ? [plugins.cssnano] : [],
-			transformOutput: (css) => {
-				return `@reference "../app.css";\n${css}`;
-			},
-		});
-		expect(result).toEqual(expected);
-	});
-
-	test('processPath should resolve @import', async () => {
-		const filePath = path.resolve(__dirname, './css/import.css');
-		const expected = '.base{color:red}.main{background:blue}';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processPath(filePath, { plugins: plugins ? Object.values(plugins) : [] });
-		expect(result).toEqual(expected);
-	});
-
-	test('processStringOrBuffer should resolve @import', async () => {
-		const string = '@import "base.css"; .main { background: blue; }';
-		const filePath = path.resolve(__dirname, './css/import.css');
-		const expected = '.base{color:red}.main{background:blue}';
-		const { plugins } = tailwindV3Preset();
-		const result = await PostCssProcessor.processStringOrBuffer(string, {
-			filePath,
-			plugins: plugins ? Object.values(plugins) : [],
-		});
-		expect(result).toEqual(expected);
-	});
-});

package/src/test/presets.test.ts

@@ -1,140 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import path from 'node:path';
-import { PostCssProcessor } from '../postcss-processor';
-import { tailwindV3Preset } from '../presets/tailwind-v3';
-import { tailwindV4Preset } from '../presets/tailwind-v4';
-
-describe('Presets Verification', () => {
-	const cssToPrefix = `
-		.test-prefix {
-			user-select: none;
-			backdrop-filter: blur(10px);
-			appearance: none;
-		}
-	`;
-
-	const cssWithImport = `
-		@import "base.css";
-		.main { background: blue; }
-	`;
-
-	test('Tailwind v3 preset should add vendor prefixes', async () => {
-		const { plugins } = tailwindV3Preset();
-		/**
-		 * Disable cssnano for readable output logic check, or just check content calls
-		 * By default preset includes cssnano.
-		 */
-
-		const result = await PostCssProcessor.processStringOrBuffer(cssToPrefix, {
-			plugins: plugins ? Object.values(plugins) : [],
-			filePath: path.resolve(__dirname, 'style.css'),
-		});
-
-		/**
-		 * cssnano will minify, so we check minified output
-		 * user-select: none -> -webkit-user-select:none;user-select:none
-		 * backdrop-filter: blur(10px) -> -webkit-backdrop-filter:blur(10px);backdrop-filter:blur(10px)
-		 * appearance: none -> -webkit-appearance:none;-moz-appearance:none;appearance:none
-		 */
-
-		expect(result).toContain('-webkit-user-select:none');
-		expect(result).toContain('user-select:none');
-
-		expect(result).toContain('-webkit-backdrop-filter:blur(10px)');
-		expect(result).toContain('backdrop-filter:blur(10px)');
-
-		expect(result).toContain('appearance:none');
-	});
-
-	test('Tailwind v3 preset should support nesting', async () => {
-		const { plugins } = tailwindV3Preset();
-		const cssWithNesting = `
-			.parent {
-				& .child { color: blue; }
-				&__element { color: green; }
-			}
-		`;
-
-		const result = await PostCssProcessor.processStringOrBuffer(cssWithNesting, {
-			plugins: plugins ? Object.values(plugins) : [],
-			filePath: path.resolve(__dirname, 'style.css'),
-		});
-
-		expect(result).toContain('.parent .child{color:blue}');
-		expect(result).toContain('.parent__element{color:green}');
-	});
-
-	test('Tailwind v4 preset should add vendor prefixes (via Lightning CSS)', async () => {
-		const preset = tailwindV4Preset({
-			referencePath: path.resolve(__dirname, '../fixtures/tailwind.css'),
-		});
-
-		const result = await PostCssProcessor.processStringOrBuffer(cssToPrefix, {
-			plugins: preset.plugins ? Object.values(preset.plugins) : [],
-			filePath: path.resolve(__dirname, 'style.css'),
-		});
-
-		/**
-		 * Lightning CSS used by @tailwindcss/postcss should verify this
-		 * Note: The specific prefixes might depend on the browser targets configured in package.json or defaults
-		 */
-
-		expect(result).toContain('-webkit-user-select:none');
-		expect(result).toContain('user-select:none');
-
-		expect(result).toContain('-webkit-backdrop-filter:blur(10px)');
-		expect(result).toContain('backdrop-filter:blur(10px)');
-
-		expect(result).toContain('appearance:none');
-	});
-
-	test('Tailwind v4 preset should resolve @import', async () => {
-		const preset = tailwindV4Preset({
-			referencePath: path.resolve(__dirname, '../fixtures/tailwind.css'),
-		});
-
-		/**
-		 * Provide a filePath that allows resolving sibling files (like base.css in existing tests/css dir)
-		 * We'll leverage the existing test css files
-		 */
-		const filePath = path.resolve(__dirname, 'css/import.css');
-
-		const result = await PostCssProcessor.processStringOrBuffer(cssWithImport, {
-			plugins: preset.plugins ? Object.values(preset.plugins) : [],
-			filePath,
-		});
-
-		/**
-		 * Expect content from base.css (.base { color: red }) + main css content
-		 * Minified output expected
-		 */
-		expect(result).toContain('.base{color:red}');
-		expect(result).toContain('.main{background:blue}');
-	});
-});
-
-test('Tailwind v4 preset should support nesting', async () => {
-	const preset = tailwindV4Preset({
-		referencePath: path.resolve(__dirname, '../fixtures/tailwind.css'),
-	});
-
-	const cssWithNesting = `
-			.parent {
-				color: red;
-				& .child {
-					color: blue;
-				}
-				&__element {
-					color: green;
-				}
-			}
-		`;
-
-	const result = await PostCssProcessor.processStringOrBuffer(cssWithNesting, {
-		plugins: preset.plugins ? Object.values(preset.plugins) : [],
-		filePath: path.resolve(__dirname, 'style.css'),
-	});
-
-	expect(result).toContain('.parent .child{color:blue}');
-	expect(result).toContain('.parent__element{color:green}');
-});