or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-normalize-url

Normalize URLs with PostCSS

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-normalize-url@7.0.x

To install, run

npx @tessl/cli install tessl/npm-postcss-normalize-url@7.0.0

index.mddocs/

PostCSS Normalize URL

PostCSS Normalize URL is a PostCSS plugin that normalizes URLs within CSS stylesheets. It automatically optimizes URL formats for better compression and standardization by removing unnecessary port numbers, converting absolute URLs to more efficient formats, normalizing relative paths, and intelligently managing quotes around URLs.

Package Information

  • Package Name: postcss-normalize-url
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install postcss-normalize-url

Core Imports

const postcssNormalizeUrl = require("postcss-normalize-url");

ES modules:

import postcssNormalizeUrl from "postcss-normalize-url";

Basic Usage

const postcss = require("postcss");
const postcssNormalizeUrl = require("postcss-normalize-url");

// Use as PostCSS plugin
const result = await postcss([postcssNormalizeUrl()])
  .process("h1 { background: url(\"http://site.com:80/image.jpg\") }", {
    from: undefined
  });

console.log(result.css);
// Output: h1 { background: url(http://site.com/image.jpg) }

Capabilities

PostCSS Plugin Creator

Creates a PostCSS plugin instance for URL normalization in CSS.

/**
 * Creates a PostCSS plugin that normalizes URLs in CSS
 * @returns {Plugin} PostCSS plugin object with postcss property
 */
function postcssNormalizeUrl(): Plugin;

// Plugin properties
postcssNormalizeUrl.postcss = true;

The plugin processes CSS and performs the following normalizations:

  • Port Removal: Removes default ports (:80 for HTTP, :443 for HTTPS)
  • Quote Optimization: Removes unnecessary quotes around URLs, adds escaping when needed
  • Path Normalization: Normalizes relative paths using Node.js path.normalize and resolves directory traversals (../)
  • Protocol Handling: Processes absolute URLs and protocol-relative URLs
  • Whitespace Handling: Removes unnecessary whitespace inside URL functions and strings
  • Multiline Support: Joins multiline URL strings that use backslash continuation
  • Special URL Preservation: Leaves data URLs and browser extension URLs unchanged
  • Fragment Preservation: Maintains URL fragments (hash portions) in both relative and absolute URLs

@namespace Rule Processing

Processes CSS @namespace rules and normalizes URLs within them.

// Plugin automatically handles @namespace rules
// Input:  @namespace url("http://example.com:80/ns");
// Output: @namespace url(http://example.com/ns);

The plugin specifically processes:

  • @namespace Rules: Converts url() functions to strings and normalizes them
  • Function to String Conversion: Transforms url() functions to quoted strings in namespace contexts
  • Quote Management: Preserves or adds appropriate quotes as needed

Types

interface Plugin {
  postcssPlugin: 'postcss-normalize-url';
  OnceExit(css: Root): void;
}

// Plugin creator function with postcss property
interface PluginCreator {
  (): Plugin;
  postcss: true;
}

// PostCSS types (from postcss package)
interface Root {
  walk(callback: (node: Node) => boolean | void): Root;
}

interface Node {
  type: string;
}

interface Declaration extends Node {
  type: 'decl';
  value: string;
}

interface AtRule extends Node {
  type: 'atrule';
  name: string;
  params: string;
}

Error Handling

The plugin includes robust error handling:

  • Malformed URLs: Invalid URLs are left unchanged rather than breaking the build
  • Data URL Parsing: Invalid data URLs fall back to the original value
  • Path Normalization: Errors in path processing don't interrupt CSS processing
  • Extension URLs: Browser extension URLs (e.g., chrome-extension://) are preserved unchanged

URL Processing Examples

Default Port Removal

/* Input */
h1 { background: url("http://site.com:80/image.jpg") }

/* Output */
h1 { background: url(http://site.com/image.jpg) }

Quote Optimization

/* Input */
h1 { background: url("simple-image.jpg") }

/* Output */
h1 { background: url(simple-image.jpg) }

Special Character Escaping

/* Input */
h1 { background: url("path with spaces.jpg") }

/* Output */
h1 { background: url("path with spaces.jpg") }

Relative Path Normalization

/* Input */
h1 { background: url("./images/../icons/icon.png") }

/* Output */
h1 { background: url(icons/icon.png) }

Directory Traversal Resolution

/* Input */
h1 { background: url("css/../font/t.eot") }

/* Output */
h1 { background: url(font/t.eot) }

Whitespace Normalization

/* Input */
h1 { background: url("           test.png      ") }

/* Output */
h1 { background: url(test.png) }

Multiline URL Handling

/* Input */
h1 { background: url("some really long string \
spanning multiple lines") }

/* Output */
h1 { background: url("some really long string spanning multiple lines") }

Fragment Preservation

/* Input */
h1 { background: url("http://website.com/test.svg#icon") }

/* Output - fragment preserved */
h1 { background: url(http://website.com/test.svg#icon) }

Data URL Preservation

/* Input */
h1 { background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==") }

/* Output - preserved unchanged */
h1 { background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==") }