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

package/src/plugin.js

@@ -0,0 +1,375 @@
+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$/
+  };
+  buildContributionsPrepared = false;
+  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)
+      })
+    ];
+  }
+  /**
+   * 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 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();
+  }
+  /**
+   * 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 || 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) {
+      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) {
+    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) {
+    const input = this.options?.transformInput && filePath ? this.options.transformInput(fileAsString, filePath) : fileAsString;
+    if (input instanceof Promise) {
+      throw new Error("transformInput must be synchronous when used with processSync");
+    }
+    return PostCssProcessor.processStringOrBufferSync(input, {
+      filePath,
+      plugins: this.postcssPlugins,
+      transformOutput: this.options?.transformOutput
+    });
+  }
+  /**
+   * Teardown the PostCSS processor.
+   */
+  async teardown() {
+    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.ts → index.d.ts}

@@ -2,6 +2,5 @@
  * 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,34 @@
+/**
+ * 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
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
+ *
+ * @example
+ * ```typescript
+ * import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+ * import { tailwindV3Preset } from '@ecopages/postcss-processor/presets';
+ *
+ * // Basic usage
+ * postcssProcessorPlugin(tailwindV3Preset())
+ *
+ * // Extend with additional plugins
+ * const preset = tailwindV3Preset();
+ * postcssProcessorPlugin({
+ *   ...preset,
+ *   plugins: { ...preset.plugins, myPlugin: myPlugin() },
+ * })
+ * ```
+ */
+export declare function tailwindV3Preset(): PostCssProcessorPluginConfig;

package/src/presets/tailwind-v3.js

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

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

@@ -0,0 +1,47 @@
+/**
+ * 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
+ * - Returns both `plugins` for immediate use and `pluginFactories` so Ecopages
+ *   can recreate fresh Tailwind/PostCSS plugin instances on dependency-driven rebuilds
+ *
+ * @example
+ * ```typescript
+ * import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+ * import { tailwindV4Preset } from '@ecopages/postcss-processor/presets';
+ *
+ * // Basic usage
+ * postcssProcessorPlugin(tailwindV4Preset({
+ *   referencePath: path.resolve(import.meta.dir, 'src/styles/tailwind.css'),
+ * }))
+ *
+ * // Extend with additional plugins
+ * const preset = tailwindV4Preset({ referencePath });
+ * postcssProcessorPlugin({
+ *   ...preset,
+ *   plugins: { ...preset.plugins, myPlugin: myPlugin() },
+ * })
+ * ```
+ */
+export declare function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProcessorPluginConfig;

package/src/presets/tailwind-v4.js

@@ -0,0 +1,57 @@
+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"]
+  };
+  const pluginFactories = {
+    "postcss-import": () => postcssImport(),
+    "postcss-nested": () => postcssNested(),
+    "@tailwindcss/postcss": () => tailwindcss({ optimize: false }),
+    autoprefixer: () => autoprefixer(autoprefixerOptions),
+    cssnano: () => cssnano()
+  };
+  return {
+    /**
+     * Instantiate the initial plugin list for the active processor instance.
+     * Fresh instances can later be recreated from `pluginFactories`.
+     */
+    plugins: Object.fromEntries(Object.entries(pluginFactories).map(([name, factory]) => [name, factory()])),
+    pluginFactories,
+    transformInput: async (contents, 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 {};