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

package/src/postcss-processor.ts

@@ -1,157 +0,0 @@
-/**
- * This module contains the PostCSS Processor
- * @module
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { Logger } from '@ecopages/logger';
-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>;
-
-const appLogger = new Logger('[@ecopages/postcss-processor]');
-
-export function getFileAsBuffer(path: string): Buffer {
-	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?: PostCssProcessorOptions): postcss.AcceptedPlugin[] => {
-	if (!options || !options.plugins) return [];
-	return Array.isArray(options.plugins) ? options.plugins : Object.values(options.plugins);
-};
-
-/**
- * It processes the given path using PostCSS
- * @param path string
- * @param options {@link PostCssProcessorOptions}
- * @returns string
- *
- * @example
- * ```ts
- * PostCssProcessor.processPath('path/to/file.css').then((processedCss) => {
- *  console.log(processedCss);
- * });\n */
-const processPath: 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 '';
-		});
-};
-
-/**
- * It processes the given string or buffer using PostCSS
- * @param contents string | Buffer
- * @param options {@link PostCssProcessorOptions}
- * @returns string
- *
- * @example
- * ```ts
- * const css = `body { @apply bg-blue-500; }`;
- *
- * PostCssProcessor.processString(css).then((processedCss) => {
- * console.log(processedCss);
- * });
- * ```
- */
-const processStringOrBuffer: 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 '';
-		});
-};
-
-export type ProcessStringOrBufferSync = (contents: string | Buffer, options?: PostCssProcessorOptions) => string;
-
-const processStringOrBufferSync: 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 as Error).message);
-		return '';
-	}
-};
-
-/**
- * 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 const PostCssProcessor: {
-	processPath: ProcessPath;
-	processStringOrBuffer: ProcessStringOrBuffer;
-	processStringOrBufferSync: ProcessStringOrBufferSync;
-} = {
-	processPath,
-	processStringOrBuffer,
-	processStringOrBufferSync,
-};

package/src/presets/tailwind-v3.ts

@@ -1,61 +0,0 @@
-/**
- * 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 autoprefixer from 'autoprefixer';
-import browserslist from 'browserslist';
-import cssnano from 'cssnano';
-import type postcss from 'postcss';
-import postcssImport from 'postcss-import';
-import tailwindcss from 'tailwindcss';
-import tailwindcssNesting from 'tailwindcss/nesting/index.js';
-import type { PostCssProcessorPluginConfig } from '../plugin.ts';
-
-type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
-
-/**
- * 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 function tailwindV3Preset(): PostCssProcessorPluginConfig {
-	// Check if browserslist config exists
-	const browserslistConfig = browserslist.loadConfig({ path: process.cwd() });
-	const autoprefixerOptions = browserslistConfig
-		? {}
-		: {
-				overrideBrowserslist: ['>0.3%', 'not ie 11', 'not dead', 'not op_mini all'],
-			};
-
-	const plugins: PluginsRecord = {
-		'postcss-import': postcssImport(),
-		'tailwindcss/nesting': tailwindcssNesting(),
-		tailwindcss: tailwindcss(),
-		autoprefixer: autoprefixer(autoprefixerOptions),
-		cssnano: cssnano(),
-	};
-
-	return { plugins };
-}

package/src/presets/tailwind-v4.ts

@@ -1,113 +0,0 @@
-/**
- * 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 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';
-import type { PostCssProcessorPluginConfig } from '../plugin.ts';
-
-/**
- * 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 function tailwindV4Preset(options: TailwindV4PresetOptions): PostCssProcessorPluginConfig {
-	const { referencePath } = options;
-
-	// Check if browserslist config exists
-	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: string | Buffer, filePath: string): Promise<string> => {
-			const css = contents instanceof Buffer ? contents.toString('utf-8') : (contents as string);
-			const normalizedFilePath = path.resolve(filePath);
-			const normalizedReferencePath = path.resolve(referencePath);
-
-			/** Skip transformation for the main tailwind entry file */
-			if (normalizedFilePath === normalizedReferencePath) {
-				return css;
-			}
-
-			/** Skip if file already has an @reference directive */
-			if (/^\s*@reference\s+/m.test(css)) {
-				return css;
-			}
-
-			const relativePath = path.relative(path.dirname(filePath), referencePath);
-
-			/** Skip if file already imports the referencePath */
-			if (css.includes(`@import '${relativePath}'`) || css.includes(`@import "${relativePath}"`)) {
-				return css;
-			}
-
-			/**
-			 * Replace `@import 'tailwindcss'` with an import to the referencePath.
-			 * This ensures custom theme variables are available for @apply directives.
-			 */
-			const tailwindImportPattern = /^@import\s+['"]tailwindcss(?:\/[^'"]*)?['"];?\s*$/m;
-			if (tailwindImportPattern.test(css)) {
-				return css.replace(tailwindImportPattern, `@import '${relativePath}';`);
-			}
-
-			/** If file uses @apply but has no tailwind import, add @reference */
-			if (css.includes('@apply')) {
-				return `@reference "${relativePath}";\n\n${css}`;
-			}
-
-			return css;
-		},
-	};
-}

package/src/runtime/css-loader-plugin.ts

@@ -1,37 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-
-import { getFileAsBuffer } from '../postcss-processor';
-import type { CssTransform } from './css-runtime-contract';
-
-type CssLoaderOptions = {
-	name: string;
-	filter: RegExp;
-	transform: CssTransform;
-};
-
-export const createCssLoaderPlugin = ({ name, filter, transform }: CssLoaderOptions): EcoBuildPlugin => ({
-	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' as const,
-				}));
-			}
-
-			return {
-				exports: {
-					default: css as string,
-				},
-				loader: 'object' as const,
-			};
-		});
-	},
-});

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

@@ -1,30 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-
-import { getFileAsBuffer } from '../postcss-processor';
-import type { CssTransform } from './css-runtime-contract';
-
-type BunCssLoaderOptions = {
-	name: string;
-	filter: RegExp;
-	transform: CssTransform;
-};
-
-export const createBunCssLoaderPlugin = ({ name, filter, transform }: BunCssLoaderOptions): EcoBuildPlugin => ({
-	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',
-			};
-		});
-	},
-});

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);
-	});
-});