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

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 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
+
+### 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.
+
+### 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.3",
   "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.3",
+    "@ecopages/file-system": "0.2.0-alpha.3",
     "@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,112 @@
+/**
+ * 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>;
+/**
+ * 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 declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
+    static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>>;
+    private postcssPlugins;
+    private pluginFactories?;
+    private readonly runtimeCssCache;
+    private readonly trackedCssFiles;
+    private watchQueue;
+    private getCssFilter;
+    private resolveProcessedCssPath;
+    private readProcessedCssFromDist;
+    private persistProcessedCss;
+    private prewarmRuntimeCssCache;
+    private transformCssSync;
+    private transformCssAsync;
+    matchesFileFilter(filepath: string): boolean;
+    private materializePluginFactories;
+    private refreshConfiguredPlugins;
+    private enqueueWatchTask;
+    private getTrackedCssFiles;
+    private handleDependencyChange;
+    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,354 @@
+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 = [];
+  pluginFactories;
+  runtimeCssCache = /* @__PURE__ */ new Map();
+  trackedCssFiles = /* @__PURE__ */ new Set();
+  watchQueue = Promise.resolve();
+  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;
+      }
+      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);
+    }
+  }
+  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);
+  }
+  materializePluginFactories(pluginFactories) {
+    return Object.values(pluginFactories).map((factory) => factory());
+  }
+  refreshConfiguredPlugins() {
+    if (!this.pluginFactories) {
+      return;
+    }
+    this.postcssPlugins = this.materializePluginFactories(this.pluginFactories);
+  }
+  enqueueWatchTask(task) {
+    const queuedTask = this.watchQueue.then(task, task);
+    this.watchQueue = queuedTask.catch(() => void 0);
+    return queuedTask;
+  }
+  getTrackedCssFiles() {
+    return Array.from(this.trackedCssFiles).filter(
+      (filePath) => this.matchesFileFilter(filePath) && fileSystem.exists(filePath)
+    );
+  }
+  async handleDependencyChange(bridge) {
+    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 = {
+    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: path2, bridge }) => {
+          await this.enqueueWatchTask(async () => {
+            if (this.matchesFileFilter(path2)) {
+              await this.handleCssChange(path2, bridge);
+              return;
+            }
+            await this.handleDependencyChange(bridge);
+          });
+        },
+        onCreate: async ({ path: path2, bridge }) => {
+          await this.enqueueWatchTask(async () => {
+            if (this.matchesFileFilter(path2)) {
+              await this.handleCssChange(path2, bridge);
+              return;
+            }
+            await this.handleDependencyChange(bridge);
+          });
+        },
+        onDelete: async ({ path: path2, bridge }) => {
+          await this.enqueueWatchTask(async () => {
+            if (this.matchesFileFilter(path2)) {
+              this.runtimeCssCache.delete(path2);
+              this.trackedCssFiles.delete(path2);
+              return;
+            }
+            await this.handleDependencyChange(bridge);
+          });
+        }
+      },
+      ...config
+    });
+  }
+  /**
+   * Handles CSS file changes during development.
+   * Processes the file and broadcasts a css-update event for hot reloading.
+   */
+  async handleCssChange(filePath, bridge, refreshPlugins = true) {
+    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() {
+    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;
+    let loadedPluginFactories;
+    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;
+        }
+        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 (loadedPluginFactories) {
+      this.pluginFactories = loadedPluginFactories;
+      this.postcssPlugins = this.materializePluginFactories(loadedPluginFactories);
+    } 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 {
+      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 = void 0;
+      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
+};