0
# PostCSS Normalize String
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: postcss-normalize-string
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript types
9
- **Installation**: `npm install postcss-normalize-string`
10

11
## Core Imports
12

13
```javascript
14
const normalizeString = require('postcss-normalize-string');
15
```
16

17
For ES modules and TypeScript:
18

19
```typescript
20
import normalizeString from 'postcss-normalize-string';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require('postcss');
27
const normalizeString = require('postcss-normalize-string');
28

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

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

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

44
## Capabilities
45

46
### Plugin Creator Function
47

48
Creates a PostCSS plugin instance with optional configuration.
49

50
```javascript { .api }
51
/**
52
 * Creates a PostCSS plugin that normalizes CSS string literals
53
 * @param opts - Configuration options for quote preference
54
 * @returns PostCSS plugin instance
55
 */
56
function normalizeString(opts?: Options): Plugin;
57
normalizeString.postcss = true;
58

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

64
interface Plugin {
65
  /** PostCSS plugin name identifier */
66
  postcssPlugin: 'postcss-normalize-string';
67
  /** Plugin processing function called once at the end */
68
  OnceExit(css: Root): void;
69
}
70
```
71

72
**Plugin Behavior:**
73
- Processes CSS rules, declarations, and at-rules containing string literals
74
- Automatically chooses optimal quote type to minimize character escaping
75
- Converts between single and double quotes based on `preferredQuote` setting
76
- Collapses multi-line string literals by removing line continuation backslashes
77
- Uses caching for performance optimization during processing
78

79
**Usage Examples:**
80

81
```javascript
82
// Default behavior (prefers double quotes)
83
const plugin = normalizeString();
84

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

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

93
### Quote Optimization Logic
94

95
The plugin applies intelligent quote optimization:
96

97
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
98
2. **Mixed Quote Handling**: When strings contain both escaped single and double quotes, no conversion is performed to avoid introducing new escapes
99
3. **Preference Enforcement**: For strings without internal quotes, the `preferredQuote` option determines the quote type
100
4. **Multi-line Collapse**: Removes line continuation backslashes (`\\\n`) to create single-line strings
101

102
**Processing Examples:**
103

104
```javascript
105
// Input with escaped single quotes
106
`p:after{content:'\\'text\\' here'}`
107
// Output (switches to double quotes to eliminate escaping)
108
`p:after{content:"'text' here"}`
109

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

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

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

126
### CSS Node Processing
127

128
The plugin processes these CSS node types:
129

130
- **Rule selectors**: Attribute selectors and pseudo-element content
131
- **Declaration values**: Property values containing string literals  
132
- **At-rule parameters**: Import URLs and other at-rule string parameters
133

134
```javascript
135
// Examples of processed CSS patterns:
136

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

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

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

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

149
// Grid template areas
150
`div{grid-template-areas:'header header' 'nav main'}` 
151
→ `div{grid-template-areas:"header header" "nav main"}`
152
```
153

154
## Types
155

156
```typescript { .api }
157
interface Options {
158
  /** 
159
   * Quote preference for strings without internal quotes
160
   * @default 'double'
161
   */
162
  preferredQuote?: 'double' | 'single';
163
}
164
```
165

166
## Dependencies
167

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

171
## Node.js Compatibility
172

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