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

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"
 });
@@ -11,8 +11,17 @@ class PostCssProcessorPlugin extends Processor {
   static DEFAULT_OPTIONS = {
     filter: /\.css$/
   };
+  buildContributionsPrepared = false;
   postcssPlugins = [];
+  pluginFactories;
   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;
   }
@@ -53,6 +62,7 @@ class PostCssProcessorPlugin extends Processor {
       if (!this.matchesFileFilter(filePath)) {
         continue;
       }
+      this.trackedCssFiles.add(filePath);
       const rawContents = await fileSystem.readFile(filePath);
       let transformedInput = rawContents;
       if (this.options?.transformInput) {
@@ -62,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);
@@ -92,6 +165,51 @@ class PostCssProcessorPlugin extends Processor {
     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)
+    );
+  }
+  getTrackedCssEntryFiles() {
+    const importedCssFiles = new Set(this.cssDependencyMap.keys());
+    return this.getTrackedCssFiles().filter((filePath) => !importedCssFiles.has(filePath));
+  }
+  getDependencyEntryFiles() {
+    const configuredEntryPaths = this.options?.dependencyEntryPaths;
+    if (!configuredEntryPaths || configuredEntryPaths.length === 0) {
+      return this.getTrackedCssEntryFiles();
+    }
+    return configuredEntryPaths.filter(
+      (filePath) => this.matchesFileFilter(filePath) && fileSystem.exists(filePath)
+    );
+  }
+  async handleDependencyChange(bridge) {
+    if (!this.context) {
+      return;
+    }
+    const cssFiles = this.getDependencyEntryFiles();
+    if (cssFiles.length === 0) {
+      return;
+    }
+    this.refreshConfiguredPlugins();
+    for (const cssFilePath of cssFiles) {
+      await this.handleCssChange(cssFilePath, bridge, false);
+    }
+  }
   constructor(config = {
     options: PostCssProcessorPlugin.DEFAULT_OPTIONS
   }) {
@@ -101,14 +219,56 @@ class PostCssProcessorPlugin extends Processor {
       capabilities: [
         {
           kind: "stylesheet",
-          extensions: ["*.css"]
+          extensions: ["*.{css,scss,sass,less}"]
         }
       ],
       watch: {
         paths: [],
-        extensions: [".css", ".scss", ".sass", ".less"],
+        extensions: [
+          ".css",
+          ".scss",
+          ".sass",
+          ".less",
+          ".tsx",
+          ".ts",
+          ".jsx",
+          ".js",
+          ".mdx",
+          ".html",
+          ".svelte",
+          ".vue"
+        ],
         onChange: async ({ path: path2, bridge }) => {
-          await this.handleCssChange(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)) {
+              this.trackedCssFiles.add(path2);
+              this.buildCssDependencyMap();
+              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);
+              this.cssDependencyMap.delete(path2);
+              this.buildCssDependencyMap();
+              return;
+            }
+            await this.handleDependencyChange(bridge);
+          });
         }
       },
       ...config
@@ -116,16 +276,44 @@ 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 handleCssChange(filePath, bridge) {
+  async processAndBroadcast(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);
@@ -155,10 +343,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();
   }
   /**
@@ -172,6 +374,7 @@ class PostCssProcessorPlugin extends Processor {
     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)) {
@@ -182,8 +385,14 @@ 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;
+        }
         if (postcssConfig && typeof postcssConfig.plugins === "object" && postcssConfig.plugins !== null) {
           if (Array.isArray(postcssConfig.plugins)) {
             loadedPlugins = postcssConfig.plugins;
@@ -203,15 +412,26 @@ class PostCssProcessorPlugin extends Processor {
     } else {
       logger.debug("No PostCSS config file found in root directory.");
     }
-    if (loadedPlugins) {
+    if (loadedPluginFactories) {
+      this.pluginFactories = loadedPluginFactories;
+      this.postcssPlugins = this.materializePluginFactories(loadedPluginFactories);
+    } else if (loadedPlugins) {
+      this.pluginFactories = void 0;
       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 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 = void 0;
       this.postcssPlugins = [];
     }
     if (!this.postcssPlugins || this.postcssPlugins.length === 0) {
@@ -226,14 +446,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/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/presets/tailwind-v3.d.ts

@@ -12,6 +12,8 @@ import type { PostCssProcessorPluginConfig } from '../plugin.js';
  * 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

package/src/presets/tailwind-v3.js

@@ -9,14 +9,17 @@ function tailwindV3Preset() {
   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()
+  const pluginFactories = {
+    "postcss-import": () => postcssImport(),
+    "tailwindcss/nesting": () => tailwindcssNesting(),
+    tailwindcss: () => tailwindcss(),
+    autoprefixer: () => autoprefixer(autoprefixerOptions),
+    cssnano: () => cssnano()
   };
-  return { plugins };
+  const plugins = Object.fromEntries(
+    Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])
+  );
+  return { plugins, pluginFactories };
 }
 export {
   tailwindV3Preset

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

@@ -23,6 +23,8 @@ export interface TailwindV4PresetOptions {
  * - Uses `@tailwindcss/postcss` plugin (v4)
  * - Automatically injects `@reference` headers for `@apply` support
  * - Includes cssnano for CSS minification
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
  *
  * @example
  * ```typescript

package/src/presets/tailwind-v4.js

@@ -11,14 +11,24 @@ function tailwindV4Preset(options) {
   const autoprefixerOptions = browserslistConfig ? {} : {
     overrideBrowserslist: [">0.3%", "not ie 11", "not dead", "not op_mini all"]
   };
+  const createTailwindPlugin = () => {
+    return tailwindcss({ optimize: false });
+  };
+  const pluginFactories = {
+    "postcss-import": () => postcssImport(),
+    "postcss-nested": () => postcssNested(),
+    "@tailwindcss/postcss": createTailwindPlugin,
+    autoprefixer: () => autoprefixer(autoprefixerOptions),
+    cssnano: () => cssnano()
+  };
   return {
-    plugins: {
-      "postcss-import": postcssImport(),
-      "postcss-nested": postcssNested(),
-      "@tailwindcss/postcss": tailwindcss(),
-      autoprefixer: autoprefixer(autoprefixerOptions),
-      cssnano: cssnano()
-    },
+    dependencyEntryPaths: [referencePath],
+    /**
+     * Instantiate the initial plugin list for the active processor instance.
+     * Fresh instances can later be recreated from `pluginFactories`.
+     */
+    plugins: Object.fromEntries(Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])),
+    pluginFactories,
     transformInput: async (contents, filePath) => {
       const css = contents instanceof Buffer ? contents.toString("utf-8") : contents;
       const normalizedFilePath = path.resolve(filePath);

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';