0
# Configuration
1

2
RTLCSS provides extensive configuration options to customize transformation behavior, including built-in options, custom plugins, and processing hooks.
3

4
## Capabilities
5

6
### Configuration Options
7

8
Core configuration options that control RTLCSS transformation behavior.
9

10
```javascript { .api }
11
interface RTLCSSOptions {
12
  /** Enable automatic CSS class renaming using string maps */
13
  autoRename?: boolean;
14
  /** Strict mode for auto-renaming - requires matching pairs */
15
  autoRenameStrict?: boolean;
16
  /** Plugin/directive blacklist to disable specific features */
17
  blacklist?: { [pluginName: string]: { [directiveName: string]: boolean } };
18
  /** Remove directive comments after processing */
19
  clean?: boolean;
20
  /** Greedy string matching mode for broader replacements */
21
  greedy?: boolean;
22
  /** Process URLs in CSS rules and at-rules */
23
  processUrls?: boolean | { atrule?: boolean };
24
  /** Custom string replacement mappings */
25
  stringMap?: StringMapEntry[];
26
  /** Use calc() function for flipping length values */
27
  useCalc?: boolean;
28
  /** Property name aliases for custom properties */
29
  aliases?: { [property: string]: string };
30
  /** Process environment-specific values like safe-area-inset */
31
  processEnv?: boolean;
32
}
33
```
34

35
**Default Options:**
36

37
```javascript
38
const defaultOptions = {
39
  autoRename: false,
40
  autoRenameStrict: false,
41
  blacklist: {},
42
  clean: true,
43
  greedy: false,
44
  processUrls: false,
45
  stringMap: [],
46
  useCalc: false,
47
  aliases: {},
48
  processEnv: true
49
};
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const rtlcss = require("rtlcss");
56

57
// Basic options
58
const options = {
59
  autoRename: true,
60
  clean: false,
61
  processUrls: true
62
};
63

64
const result = rtlcss.process(css, options);
65

66
// Advanced options with custom string maps
67
const advancedOptions = {
68
  autoRename: true,
69
  autoRenameStrict: true,
70
  greedy: true,
71
  stringMap: [
72
    {
73
      name: 'theme-names',
74
      search: ['light-theme', 'dark-theme'],
75
      replace: ['مظهر-فاتح', 'مظهر-داكن'],
76
      priority: 100,
77
      options: { scope: 'selector' }
78
    }
79
  ],
80
  aliases: {
81
    'custom-margin-start': 'margin-left',
82
    'custom-margin-end': 'margin-right'
83
  },
84
  blacklist: {
85
    rtlcss: {
86
      ignore: false,
87
      rename: true  // Disable rename directive
88
    }
89
  }
90
};
91
```
92

93
### String Maps
94

95
Custom string replacement system for transforming text in CSS selectors and URLs.
96

97
```javascript { .api }
98
interface StringMapEntry {
99
  /** Unique identifier for the string map */
100
  name: string;
101
  /** Processing priority (lower numbers processed first) */
102
  priority: number;
103
  /** String or array of strings to search for */
104
  search: string | string[];
105
  /** Replacement string or array of replacement strings */
106
  replace: string | string[];
107
  /** Stop processing other maps if this one matches */
108
  exclusive?: boolean;
109
  /** Scope and case sensitivity options */
110
  options?: StringMapOptions;
111
}
112

113
interface StringMapOptions {
114
  /** Where to apply the string map */
115
  scope?: '*' | 'url' | 'selector';
116
  /** Case-insensitive matching */
117
  ignoreCase?: boolean;
118
  /** Use greedy matching (overrides global greedy setting) */
119
  greedy?: boolean;
120
}
121
```
122

123
**Built-in String Maps:**
124

125
RTLCSS automatically includes these string maps if not explicitly provided:
126

127
```javascript
128
// Left-right transformation
129
{
130
  name: 'left-right',
131
  priority: 100,
132
  search: ['left', 'Left', 'LEFT'],
133
  replace: ['right', 'Right', 'RIGHT'],
134
  options: { scope: '*', ignoreCase: false }
135
}
136

137
// LTR-RTL transformation
138
{
139
  name: 'ltr-rtl',
140
  priority: 100,
141
  search: ['ltr', 'Ltr', 'LTR'],
142
  replace: ['rtl', 'Rtl', 'RTL'],
143
  options: { scope: '*', ignoreCase: false }
144
}
145
```
146

147
**Usage Examples:**
148

149
```javascript
150
const stringMaps = [
151
  {
152
    name: 'navigation',
153
    priority: 50,
154
    search: ['nav-left', 'nav-right'],
155
    replace: ['nav-start', 'nav-end'],
156
    options: { scope: 'selector', ignoreCase: true }
157
  },
158
  {
159
    name: 'images',
160
    priority: 75,
161
    search: '/images/ltr/',
162
    replace: '/images/rtl/',
163
    options: { scope: 'url' }
164
  },
165
  {
166
    name: 'exclusive-brand',
167
    priority: 25,
168
    search: 'brand-primary',
169
    replace: 'علامة-أساسية',
170
    exclusive: true,  // Stop processing other maps
171
    options: { scope: 'selector' }
172
  }
173
];
174

175
const result = rtlcss.process(css, { stringMap: stringMaps });
176
```
177

178
### Configuration Loading
179

180
Load configuration from files or create configurations programmatically.
181

182
```javascript { .api }
183
const configLoader = require("rtlcss/lib/config-loader");
184

185
/**
186
 * Load configuration from file or search for config files
187
 * @param configFilePath - Explicit path to config file
188
 * @param cwd - Current working directory for config search
189
 * @param overrides - Override values to merge with loaded config
190
 * @returns Configuration object or null if not found
191
 */
192
function load(configFilePath?: string, cwd?: string, overrides?: any): RTLCSSConfiguration | null;
193
```
194

195
**Configuration Sources (searched in order):**
196

197
1. Specified config file path
198
2. `.rtlcssrc` file (current/parent directories)
199
3. `.rtlcss.json` file (current/parent directories)
200
4. `rtlcssConfig` property in `package.json`
201
5. User home directory configs
202

203
**Usage Examples:**
204

205
```javascript
206
const configLoader = require("rtlcss/lib/config-loader");
207

208
// Load from specific file
209
const config = configLoader.load('./my-rtlcss-config.json');
210

211
// Search for config in current directory
212
const config = configLoader.load();
213

214
// Search with overrides
215
const config = configLoader.load(null, process.cwd(), {
216
  options: { autoRename: true }
217
});
218

219
// Use loaded config
220
if (config) {
221
  const processor = rtlcss.configure(config);
222
  const result = processor.process(css).css;
223
}
224
```
225

226
**Example Configuration Files:**
227

228
`.rtlcssrc`:
229
```json
230
{
231
  "options": {
232
    "autoRename": true,
233
    "clean": false,
234
    "stringMap": [
235
      {
236
        "name": "custom-directions",
237
        "search": ["start", "end"],
238
        "replace": ["بداية", "نهاية"],
239
        "priority": 100
240
      }
241
    ]
242
  },
243
  "plugins": [],
244
  "hooks": {}
245
}
246
```
247

248
`package.json`:
249
```json
250
{
251
  "name": "my-app",
252
  "rtlcssConfig": {
253
    "options": {
254
      "processUrls": true,
255
      "autoRename": true
256
    }
257
  }
258
}
259
```
260

261
### Plugin System
262

263
Extend RTLCSS functionality with custom plugins.
264

265
```javascript { .api }
266
interface RTLCSSPlugin {
267
  /** Unique plugin identifier */
268
  name: string;
269
  /** Processing priority (lower numbers processed first) */
270
  priority: number;
271
  /** Control and value directives */
272
  directives?: {
273
    control?: { [name: string]: DirectiveHandler };
274
    value?: DirectiveHandler[];
275
  };
276
  /** CSS property processors */
277
  processors?: PropertyProcessor[];
278
}
279

280
interface PropertyProcessor {
281
  /** Regular expression matching CSS properties */
282
  expr: RegExp;
283
  /** Processing function for matched properties */
284
  action: (prop: string, value: string, context: ProcessingContext) => PropertyResult;
285
}
286

287
interface PropertyResult {
288
  /** Transformed property name */
289
  prop: string;
290
  /** Transformed property value */
291
  value: string;
292
}
293
```
294

295
**Usage Examples:**
296

297
```javascript
298
// Custom plugin for handling CSS Grid properties
299
const gridPlugin = {
300
  name: 'css-grid',
301
  priority: 75,
302
  processors: [
303
    {
304
      expr: /^grid-template-areas$/,
305
      action: (prop, value, context) => {
306
        // Reverse grid template areas for RTL
307
        const reversedValue = value
308
          .split('\n')
309
          .map(line => line.trim().split(' ').reverse().join(' '))
310
          .join('\n');
311
        
312
        return { prop: prop, value: reversedValue };
313
      }
314
    },
315
    {
316
      expr: /^grid-column-(start|end)$/,
317
      action: (prop, value, context) => {
318
        // Swap grid column start/end
319
        const newProp = prop.includes('start') 
320
          ? prop.replace('start', 'end')
321
          : prop.replace('end', 'start');
322
        
323
        return { prop: newProp, value: value };
324
      }
325
    }
326
  ]
327
};
328

329
// Use custom plugin
330
const result = rtlcss.process(css, {}, [gridPlugin]);
331
```