tessl/npm-postcss-url

PostCSS plugin to rebase, inline, or copy assets from url() declarations with support for multiple transformation modes and advanced filtering options.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Plugin Configuration

Name: tessl/npm-postcss-url
Author: tessl

PostCSS URL plugin configuration system supporting single options objects, arrays of options for multi-mode processing, and comprehensive option validation.

Capabilities

Single Option Configuration

Configure the plugin with a single options object for uniform processing of all matching assets.

/**
 * Configure plugin with single options object
 * @param {PostcssUrlOptions} options - Configuration options
 * @returns {PostcssPlugin} Configured plugin instance
 */
function postcssUrl(options: PostcssUrlOptions): PostcssPlugin;

Usage Example:

const postcss = require('postcss');
const postcssUrl = require('postcss-url');

// Single option configuration
const result = await postcss()
  .use(postcssUrl({
    url: 'inline',
    maxSize: 10,
    fallback: 'copy',
    assetsPath: 'assets'
  }))
  .process(css, { from: 'src/main.css', to: 'dist/main.css' });

Multiple Options Configuration

Configure the plugin with an array of options for selective processing based on filters and priorities.

/**
 * Configure plugin with multiple options for selective processing
 * @param {PostcssUrlOptions[]} options - Array of configuration options
 * @returns {PostcssPlugin} Configured plugin instance
 */
function postcssUrl(options: PostcssUrlOptions[]): PostcssPlugin;

Usage Example:

// Multiple options with filtering
const result = await postcss()
  .use(postcssUrl([
    // Copy PNG files with hash names
    {
      filter: '**/*.png',
      url: 'copy',
      assetsPath: 'images',
      useHash: true
    },
    // Inline small SVG files
    {
      filter: '**/*.svg',
      url: 'inline',
      maxSize: 5,
      fallback: 'copy'
    },
    // CDN transform for specific paths
    {
      filter: /^\/cdn\//,
      url: (asset) => `https://cdn.example.com${asset.url}`
    },
    // Default rebase for everything else
    {
      url: 'rebase'
    }
  ]))
  .process(css, { from: 'src/main.css', to: 'dist/main.css' });

Default Plugin Configuration

Use the plugin without options to apply default rebase behavior.

/**
 * Use plugin with default options (rebase mode)
 * @returns {PostcssPlugin} Plugin with default configuration
 */
function postcssUrl(): PostcssPlugin;

Usage Example:

// Default configuration (rebase mode)
const result = await postcss()
  .use(postcssUrl()) // No options = rebase mode
  .process(css, { from: 'src/main.css', to: 'dist/main.css' });

Option Processing Order

When using multiple options, the plugin processes them in array order and uses the first matching option based on filter criteria.

interface OptionMatching {
  /** Options are processed in array order */
  order: 'first-to-last';
  /** First matching filter is used */
  selection: 'first-match';
  /** Multi-option processing available with custom functions */
  multi: boolean;
}

Multi-Option Processing Example:

// Custom function with multi: true allows chaining
const options = [
  {
    filter: '**/*.png',
    url: (asset) => {
      console.log(`Processing: ${asset.url}`);
      return asset.url; // Pass through for next option
    },
    multi: true // Allow processing by subsequent options
  },
  {
    filter: '**/*.png',
    url: 'copy',
    assetsPath: 'images'
  }
];

Configuration Validation

The plugin validates configuration options and provides meaningful error messages for invalid configurations.

interface ValidationErrors {
  /** Unknown processing mode error */
  'Unknown mode for postcss-url': string;
  /** Missing required assetsPath for copy mode */
  'Option `to` of postcss is required': string;
  /** Invalid filter pattern */
  'Invalid filter pattern': string;
}

Error Handling Example:

try {
  const result = await postcss()
    .use(postcssUrl({
      url: 'invalid-mode' // This will throw an error
    }))
    .process(css, { from: 'src/main.css', to: 'dist/main.css' });
} catch (error) {
  console.error('Plugin configuration error:', error.message);
}

PostCSS Integration

The plugin integrates with PostCSS processing pipeline and requires PostCSS options for proper path resolution.

interface PostcssIntegration {
  /** PostCSS 'from' option used for source path resolution */
  from: string;
  /** PostCSS 'to' option used for target path resolution */
  to: string;
  /** Plugin processes CSS declarations during 'Once' phase */
  phase: 'Once';
}

PostCSS Options Example:

const result = await postcss()
  .use(postcssUrl(options))
  .process(css, {
    from: path.resolve('src/styles/main.css'),    // Source file path
    to: path.resolve('dist/styles/main.css')      // Target file path
  });

Install with Tessl CLI