v 0.1.57

PostCSS Processor

The @ecopages/postcss-processor package provides a PostCSS processor plugin for Ecopages that handles CSS processing and transformation. It includes built-in presets for Tailwind CSS (v3 and v4) and supports custom configurations.

Installation

Install the package from JSR:

bunx jsr add @ecopages/postcss-processor

Presets

The processor comes with presets to get you started quickly with popular setups.

Tailwind v3 Preset

This preset includes the standard Tailwind CSS v3 stack: tailwindcss, tailwindcss/nesting, autoprefixer, postcss-import, and cssnano.

bun add -D [email protected]
import { ConfigBuilder } from '@ecopages/core';
import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
 
const config = await new ConfigBuilder()
  .setProcessors([
    postcssProcessorPlugin(tailwindV3Preset())
  ])
  .build();
 
export default config;

Tailwind v4 Preset (Recommended)

This preset supports Tailwind CSS v4, utilizing @tailwindcss/postcss. It includes autoprefixer, postcss-nested, and cssnano by default. It also automatically handles @reference injection for @apply directives, making usage simpler in isolated component styles.

bun add -D @tailwindcss/postcss tailwindcss
import path from 'node:path';
import { ConfigBuilder } from '@ecopages/core';
import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
import { tailwindV4Preset } from '@ecopages/postcss-processor/presets/tailwind-v4';
 
const config = await new ConfigBuilder()
  .setProcessors([
    postcssProcessorPlugin(tailwindV4Preset({
      // Path to your main CSS file containing `@import "tailwindcss";`
      referencePath: path.resolve(import.meta.dir, 'src/styles/app.css'),
    }))
  ])
  .build();
 
export default config;

Browser Support

By default, the presets target a broad range of modern browsers (>0.3%, not ie 11, not dead, not op_mini all).

To override this, add a browserslist configuration to your package.json or create a .browserslistrc file in your project root. The processor will automatically detect and use your custom configuration.

Custom Configuration

If you prefer full control or need different plugins, you can configure the processor manually.

Using postcss.config.js

The plugin automatically detects and uses standard postcss.config.{js,cjs,mjs,ts} files from your project root. This is the most compatible way to configure PostCSS.

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-import': {},
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
    cssnano: {},
  },
};

Then simply add the plugin without arguments:

// eco.config.ts
import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
 
const config = await new ConfigBuilder()
  .setProcessors([
    postcssProcessorPlugin()
  ])
  .build();

Manual Plugin Configuration

You can also pass options directly to the plugin factory:

import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
import myPlugin from 'postcss-my-plugin';
 
postcssProcessorPlugin({
  filter: /\.css$/,
  plugins: {
    'my-plugin': myPlugin(),
  },
})

Advanced Configuration

For advanced use cases, you can customize the processor with transformation hooks to modify CSS before or after PostCSS processing:

import { ConfigBuilder } from '@ecopages/core';
import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
 
const config = await new ConfigBuilder()
  .setProcessors([
    postcssProcessorPlugin({
      // Define a filter for files to process (defaults to /\.css$/)
      filter: /\.css$/,
      // Provide a function to transform input before processing
      transformInput: async (css) => `/* My Custom Header */\n${css}`,
      // Provide a function to transform output after processing
      transformOutput: async (css) => css.replace('blue', 'red'),
      // Explicitly provide plugins (overrides defaults)
      plugins: {
        /* custom plugins */
      },
    }),
  ])
  .build();
 
export default config;

Using with Bun

To enable CSS imports in your TypeScript/JavaScript files (e.g., import styles from './styles.css'), you must add the postcssProcessorPlugin to your eco.config.ts as shown above.

This plugin automatically registers a Bun loader that processes your CSS files on import, rendering the deprecated @ecopages/bun-postcss-loader unnecessary.

// Component.ts
import styles from './styles.css';
 
// styles is the processed CSS string
console.log(styles);

Processing Methods

The processor also exports standalone methods if you need to process CSS programmatically:

import { PostCssProcessor } from '@ecopages/postcss-processor';
 
// Process a file
const cssFromFile = await PostCssProcessor.processPath('path/to/file.css');
 
// Process a string
const cssString = await PostCssProcessor.processStringOrBuffer(
  '.foo { @apply bg-red-500; }', 
  { filePath: 'mock.css' }
);

Error Handling

The processor includes built-in error handling: