0
# Configuration Options
1

2
Comprehensive configuration system for customizing prettier-plugin-tailwindcss behavior including Tailwind config paths, custom attributes, function names, and formatting preferences.
3

4
## Capabilities
5

6
### Plugin Options Interface
7

8
Main configuration interface defining all available plugin options that can be set in your Prettier configuration.
9

10
```typescript { .api }
11
interface PluginOptions {
12
  /** Path to Tailwind configuration file */
13
  tailwindConfig?: string;
14
  /** Path to the CSS stylesheet in your Tailwind project (v4+) */
15
  tailwindStylesheet?: string;
16
  /** Path to the CSS entrypoint in your Tailwind project (v4+) @deprecated Use tailwindStylesheet instead */
17
  tailwindEntryPoint?: string;
18
  /** List of functions and tagged templates that contain sortable Tailwind classes */
19
  tailwindFunctions?: string[];
20
  /** List of attributes/props that contain sortable Tailwind classes */
21
  tailwindAttributes?: string[];
22
  /** Preserve whitespace around Tailwind classes when sorting */
23
  tailwindPreserveWhitespace?: boolean;
24
  /** Preserve duplicate classes inside a class list when sorting */
25
  tailwindPreserveDuplicates?: boolean;
26
  /** The package name to use when loading Tailwind CSS */
27
  tailwindPackageName?: string;
28
}
29
```
30

31
### Tailwind Configuration Path
32

33
Specify the path to your Tailwind configuration file for custom class ordering. By default, the plugin searches for common Tailwind config file names in your project.
34

35
**Usage Examples:**
36

37
```json
38
{
39
  "plugins": ["prettier-plugin-tailwindcss"],
40
  "tailwindConfig": "./tailwind.config.js"
41
}
42
```
43

44
```json
45
{
46
  "plugins": ["prettier-plugin-tailwindcss"],
47
  "tailwindConfig": "./config/tailwind.config.ts"
48
}
49
```
50

51
**Automatic Discovery:**
52

53
If not specified, the plugin automatically searches for:
54
- `tailwind.config.js`
55
- `tailwind.config.cjs` 
56
- `tailwind.config.mjs`
57
- `tailwind.config.ts`
58

59
### Tailwind v4 Stylesheet Path
60

61
For Tailwind CSS v4+, specify the CSS entry point containing your theme and configuration.
62

63
**Usage Example:**
64

65
```json
66
{
67
  "plugins": ["prettier-plugin-tailwindcss"],
68
  "tailwindStylesheet": "./src/styles/app.css"
69
}
70
```
71

72
The stylesheet should contain your Tailwind directives and custom CSS:
73

74
```css
75
@import "tailwindcss";
76

77
/* Your custom styles and configuration */
78
@layer components {
79
  .btn-primary {
80
    @apply bg-blue-500 text-white px-4 py-2 rounded;
81
  }
82
}
83
```
84

85
### Custom Attributes
86

87
Configure additional HTML attributes that should have their classes sorted beyond the default `class` and `className` attributes.
88

89
**Usage Examples:**
90

91
```json
92
{
93
  "plugins": ["prettier-plugin-tailwindcss"],
94
  "tailwindAttributes": ["myClassList", "customClass"]
95
}
96
```
97

98
This enables sorting in custom attributes:
99

100
```jsx
101
// Before
102
<div myClassList="px-4 bg-blue-500 text-white py-2">Content</div>
103

104
// After  
105
<div myClassList="bg-blue-500 px-4 py-2 text-white">Content</div>
106
```
107

108
**Framework-Specific Behavior:**
109

110
```json
111
{
112
  "tailwindAttributes": ["x-bind:class", "wire:class", "my-classes"]
113
}
114
```
115

116
### Custom Functions
117

118
Configure function names that contain class strings to be sorted. Useful for utility libraries like `clsx`, `classNames`, or custom helper functions.
119

120
**Usage Examples:**
121

122
```json
123
{
124
  "plugins": ["prettier-plugin-tailwindcss"],
125
  "tailwindFunctions": ["clsx", "cn", "classNames", "tw"]
126
}
127
```
128

129
This enables sorting inside function calls:
130

131
```javascript
132
// Before
133
const classes = clsx("px-4 bg-blue-500 text-white py-2");
134

135
// After
136
const classes = clsx("bg-blue-500 px-4 py-2 text-white");
137
```
138

139
**Advanced Function Usage:**
140

141
```javascript
142
// Template literals with tagged templates
143
const styles = tw`px-4 bg-blue-500 text-white py-2`;
144

145
// Nested function calls
146
const buttonClass = cn(
147
  "base-button",
148
  clsx("px-4 bg-blue-500 text-white py-2", {
149
    "opacity-50": disabled
150
  })
151
);
152

153
// Method chaining
154
const dynamicClass = ClassBuilder()
155
  .add("px-4 bg-blue-500 text-white py-2")
156
  .build();
157
```
158

159
### Whitespace Preservation
160

161
Control whether whitespace around classes is preserved during sorting. By default, whitespace is normalized to single spaces.
162

163
**Usage Example:**
164

165
```json
166
{
167
  "plugins": ["prettier-plugin-tailwindcss"],
168
  "tailwindPreserveWhitespace": true
169
}
170
```
171

172
**Behavior:**
173

174
```html
175
<!-- With tailwindPreserveWhitespace: false (default) -->
176
<div class="  px-4   bg-blue-500  text-white  py-2  ">
177
<!-- Becomes: -->
178
<div class="bg-blue-500 px-4 py-2 text-white">
179

180
<!-- With tailwindPreserveWhitespace: true -->
181
<div class="  px-4   bg-blue-500  text-white  py-2  ">
182
<!-- Becomes: -->
183
<div class="  bg-blue-500   px-4  py-2  text-white  ">
184
```
185

186
### Duplicate Class Preservation
187

188
Control whether duplicate classes are preserved or removed during sorting. By default, duplicate classes are removed.
189

190
**Usage Example:**
191

192
```json
193
{
194
  "plugins": ["prettier-plugin-tailwindcss"],
195
  "tailwindPreserveDuplicates": true
196
}
197
```
198

199
**Behavior:**
200

201
```html
202
<!-- With tailwindPreserveDuplicates: false (default) -->
203
<div class="px-4 bg-blue-500 px-4 text-white">
204
<!-- Becomes: -->
205
<div class="bg-blue-500 px-4 text-white">
206

207
<!-- With tailwindPreserveDuplicates: true -->
208
<div class="px-4 bg-blue-500 px-4 text-white">
209
<!-- Becomes: -->
210
<div class="bg-blue-500 px-4 px-4 text-white">
211
```
212

213
### Package Name Override
214

215
Specify a custom package name to use when loading Tailwind CSS. Useful for custom Tailwind builds or alternative distributions.
216

217
**Usage Example:**
218

219
```json
220
{
221
  "plugins": ["prettier-plugin-tailwindcss"],
222
  "tailwindPackageName": "@my-org/tailwindcss"
223
}
224
```
225

226
**Default Behavior:**
227

228
By default, the plugin uses `"tailwindcss"` as the package name. This option allows you to:
229

230
- Use custom Tailwind CSS builds with different package names
231
- Load Tailwind CSS from forked or modified versions
232
- Work with monorepo setups that have renamed the Tailwind package
233

234
**Example with Custom Build:**
235

236
```json
237
{
238
  "plugins": ["prettier-plugin-tailwindcss"],
239
  "tailwindPackageName": "tailwindcss-custom",
240
  "tailwindConfig": "./tailwind.config.js"
241
}
242
```
243

244
## Complete Configuration Example
245

246
**Prettier Configuration (`.prettierrc`):**
247

248
```json
249
{
250
  "plugins": ["prettier-plugin-tailwindcss"],
251
  "tailwindConfig": "./tailwind.config.js",
252
  "tailwindAttributes": [
253
    "myClassList",
254
    "x-bind:class",
255
    "wire:class"
256
  ],
257
  "tailwindFunctions": [
258
    "clsx",
259
    "cn", 
260
    "classNames",
261
    "tw"
262
  ],
263
  "tailwindPreserveWhitespace": false,
264
  "tailwindPreserveDuplicates": false,
265
  "tailwindPackageName": "tailwindcss"
266
}
267
```
268

269
**Package.json Script:**
270

271
```json
272
{
273
  "scripts": {
274
    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,html,css}\""
275
  }
276
}
277
```
278

279
## Configuration File Locations
280

281
The plugin configuration can be specified in any of Prettier's supported configuration files:
282

283
- `.prettierrc`
284
- `.prettierrc.json`
285
- `.prettierrc.js`
286
- `.prettierrc.mjs`
287
- `.prettierrc.cjs`
288
- `prettier.config.js`
289
- `prettier.config.mjs`
290
- `prettier.config.cjs`
291
- `package.json` (in a `prettier` field)
292

293
**Example in `prettier.config.js`:**
294

295
```javascript
296
export default {
297
  plugins: ["prettier-plugin-tailwindcss"],
298
  tailwindConfig: "./tailwind.config.js",
299
  tailwindFunctions: ["clsx", "cn"],
300
  tailwindAttributes: ["customClass"]
301
};
302
```