or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-normalize-string

Normalize wrapping quotes for CSS string literals in PostCSS pipelines.

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

To install, run

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

index.mddocs/

PostCSS Normalize String

PostCSS Normalize String is a PostCSS plugin that normalizes CSS string literals by standardizing their wrapping quotes. It optimizes quote usage for better CSS compression, handles escaped quotes within string content, and provides configurable quote preference options.

Package Information

  • Package Name: postcss-normalize-string
  • Package Type: npm
  • Language: JavaScript with TypeScript types
  • Installation: npm install postcss-normalize-string

Core Imports

const normalizeString = require('postcss-normalize-string');

For ES modules and TypeScript:

import normalizeString from 'postcss-normalize-string';

Basic Usage

const postcss = require('postcss');
const normalizeString = require('postcss-normalize-string');

// With default options (double quotes preferred)
const processor = postcss([normalizeString()]);

// With custom options
const processorSingle = postcss([
  normalizeString({ preferredQuote: 'single' })
]);

// Process CSS
const input = `p:after{content:'\\'string\\' is intact'}`;
const result = processor.process(input, {from: undefined});
console.log(result.css);
// Output: p:after{content:"'string' is intact"}

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance with optional configuration.

/**
 * Creates a PostCSS plugin that normalizes CSS string literals
 * @param opts - Configuration options for quote preference
 * @returns PostCSS plugin instance
 */
function normalizeString(opts?: Options): Plugin;
normalizeString.postcss = true;

interface Options {
  /** Quote preference: 'double' (default) or 'single' */
  preferredQuote?: 'double' | 'single';
}

interface Plugin {
  /** PostCSS plugin name identifier */
  postcssPlugin: 'postcss-normalize-string';
  /** Plugin processing function called once at the end */
  OnceExit(css: Root): void;
}

Plugin Behavior:

  • Processes CSS rules, declarations, and at-rules containing string literals
  • Automatically chooses optimal quote type to minimize character escaping
  • Converts between single and double quotes based on preferredQuote setting
  • Collapses multi-line string literals by removing line continuation backslashes
  • Uses caching for performance optimization during processing

Usage Examples:

// Default behavior (prefers double quotes)
const plugin = normalizeString();

// Prefer single quotes
const pluginSingle = normalizeString({ preferredQuote: 'single' });

// Use with PostCSS
const postcss = require('postcss');
const result = postcss([normalizeString()]).process(cssString, {from: undefined});

Quote Optimization Logic

The plugin applies intelligent quote optimization:

  1. Automatic Optimization: When a string contains escaped quotes of the current type but not the alternate type, it switches quote types to eliminate escaping
  2. Mixed Quote Handling: When strings contain both escaped single and double quotes, no conversion is performed to avoid introducing new escapes
  3. Preference Enforcement: For strings without internal quotes, the preferredQuote option determines the quote type
  4. Multi-line Collapse: Removes line continuation backslashes (\\\n) to create single-line strings

Processing Examples:

// Input with escaped single quotes
`p:after{content:'\\'text\\' here'}`
// Output (switches to double quotes to eliminate escaping)
`p:after{content:"'text' here"}`

// Input with escaped double quotes  
`p:after{content:"\\"text\\" here"}`
// Output (switches to single quotes to eliminate escaping)
`p:after{content:'"text" here'}`

// Input with mixed escaped quotes (no change)
`p:after{content:"\\"text\\" and 'more'"}` 
// Output (preserves original to avoid new escapes)
`p:after{content:"\\"text\\" and 'more'"}`

// Input with line continuations
`p:after{content:"line one\\\nline two"}`
// Output (collapses to single line)
`p:after{content:"line oneline two"}`

CSS Node Processing

The plugin processes these CSS node types:

  • Rule selectors: Attribute selectors and pseudo-element content
  • Declaration values: Property values containing string literals
  • At-rule parameters: Import URLs and other at-rule string parameters
// Examples of processed CSS patterns:

// Attribute selectors
`[data-content='text']` → `[data-content="text"]`

// Content property
`p:after{content:'text'}` → `p:after{content:"text"}`

// Font family names
`p{font-family:'Comic Sans'}` → `p{font-family:"Comic Sans"}`

// Import statements
`@import url('styles.css')` → `@import url("styles.css")`

// Grid template areas
`div{grid-template-areas:'header header' 'nav main'}` 
→ `div{grid-template-areas:"header header" "nav main"}`

Types

interface Options {
  /** 
   * Quote preference for strings without internal quotes
   * @default 'double'
   */
  preferredQuote?: 'double' | 'single';
}

Dependencies

  • postcss-value-parser: ^4.2.0 - Used for parsing CSS values and handling string content
  • postcss: ^8.4.32 (peer dependency) - PostCSS framework for CSS processing

Node.js Compatibility

  • Required Node.js versions: ^18.12.0 || ^20.9.0 || >=22.0
  • Tested environments: Modern Node.js LTS versions
  • Browser support: Not applicable (build-time tool)