0
# TSLint Plugin Prettier
1
2
TSLint Plugin Prettier integrates Prettier code formatting into the TSLint linting workflow. It runs Prettier as a TSLint rule and reports formatting differences as individual TSLint issues, enabling teams to enforce consistent code formatting through their existing TSLint setup with automatic fix suggestions.
3
4
## Package Information
5
6
- **Package Name**: tslint-plugin-prettier
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev tslint-plugin-prettier prettier`
10
11
## Core Imports
12
13
The package is used as a TSLint plugin, not directly imported in code. It extends TSLint's rule system:
14
15
```json
16
{
17
"rulesDirectory": ["tslint-plugin-prettier"],
18
"rules": {
19
"prettier": true
20
}
21
}
22
```
23
24
For TSLint 5.0.0+, you can also use the extends syntax:
25
26
```json
27
{
28
"extends": ["tslint-plugin-prettier"],
29
"rules": {
30
"prettier": true
31
}
32
}
33
```
34
35
## Basic Usage
36
37
Add the prettier rule to your `tslint.json` configuration:
38
39
```json
40
{
41
"rulesDirectory": ["tslint-plugin-prettier"],
42
"rules": {
43
"prettier": true
44
}
45
}
46
```
47
48
The plugin will automatically:
49
1. Run Prettier formatting on your TypeScript/JavaScript files
50
2. Compare the formatted output with the original source
51
3. Report differences as TSLint failures with automatic fix suggestions
52
4. Respect `.prettierignore` files to exclude files from formatting
53
54
## Capabilities
55
56
### TSLint Plugin Configuration
57
58
The main export provides TSLint plugin configuration that registers the prettier rule.
59
60
```typescript { .api }
61
// Main plugin export (rules/index.js)
62
export = {
63
rulesDirectory: string; // Value: '.'
64
};
65
```
66
67
### Prettier Rule Implementation
68
69
The core rule that integrates Prettier formatting into TSLint.
70
71
```typescript { .api }
72
// prettier rule (rules/prettierRule.js)
73
export class Rule extends tslint.Rules.AbstractRule {
74
/**
75
* Apply the prettier rule to a TypeScript source file
76
* @param sourceFile - TypeScript source file to analyze
77
* @returns Array of TSLint rule failures for formatting differences
78
*/
79
apply(sourceFile: ts.SourceFile): tslint.RuleFailure[];
80
}
81
```
82
83
### Rule Configuration Options
84
85
The prettier rule accepts flexible configuration options:
86
87
**Basic Usage (auto-config)**:
88
```json
89
{
90
"rules": {
91
"prettier": true
92
}
93
}
94
```
95
96
**With Prettier Options Object**:
97
```json
98
{
99
"rules": {
100
"prettier": [true, { "singleQuote": true, "trailingComma": "es5" }]
101
}
102
}
103
```
104
105
**With Config File Path**:
106
```json
107
{
108
"rules": {
109
"prettier": [true, "configs/.prettierrc"]
110
}
111
}
112
```
113
114
**With Additional Options**:
115
```json
116
{
117
"rules": {
118
"prettier": [true, null, {
119
"editorconfig": false,
120
"ignorePath": "custom.prettierignore"
121
}]
122
}
123
}
124
```
125
126
## Configuration Arguments
127
128
```typescript { .api }
129
// Rule configuration signature
130
type PrettierRuleConfig = [
131
boolean, // Enable rule
132
PrettierOptions | string | null?, // Prettier config object, config file path, or null for auto-discovery
133
AdditionalOptions? // Additional plugin options
134
];
135
136
interface PrettierOptions {
137
// Standard Prettier options (singleQuote, trailingComma, etc.)
138
[key: string]: any;
139
}
140
141
interface AdditionalOptions {
142
/** Whether to load .editorconfig files (default: true) */
143
editorconfig?: boolean;
144
/** Path to custom .prettierignore file (default: '.prettierignore') */
145
ignorePath?: string;
146
}
147
```
148
149
## Integration Details
150
151
### File Processing Logic
152
153
The rule follows this processing flow:
154
155
1. **Ignore Check**: Uses `prettier.getFileInfo.sync()` to check if file should be ignored via `.prettierignore`
156
2. **Config Resolution**: Resolves Prettier configuration from rule arguments, config files, or defaults
157
3. **Formatting**: Runs `prettier.format()` with TypeScript parser on source code
158
4. **Comparison**: Compares original source with formatted output
159
5. **Failure Generation**: Creates TSLint failures for differences with automatic fixes
160
161
### Error Handling
162
163
The rule handles two types of issues:
164
165
**Syntax Errors**: When Prettier encounters invalid TypeScript syntax
166
```typescript { .api }
167
// Reported as TSLint failure with location information
168
type SyntaxErrorFailure = {
169
message: `SyntaxError: ${string}`;
170
position: number;
171
length: 1;
172
};
173
```
174
175
**Formatting Differences**: When code doesn't match Prettier's formatting
176
```typescript { .api }
177
// Three types of formatting fixes
178
type FormattingFailureType = 'insert' | 'delete' | 'replace';
179
180
interface FormattingFailure {
181
operation: FormattingFailureType;
182
message: string; // e.g., "Insert ` `", "Delete `;;`", "Replace `''` with `"";`"
183
fix: tslint.Replacement; // Automatic fix suggestion
184
}
185
```
186
187
### Dependencies Integration
188
189
The plugin integrates with several key dependencies:
190
191
- **eslint-plugin-prettier**: Provides `generateDifferences()` and `showInvisibles()` utilities for comparing formatted code
192
- **lines-and-columns**: Maps character positions to line/column coordinates for error reporting
193
- **prettier**: Core formatting engine with TypeScript parser support
194
- **tslint**: Extends `tslint.Rules.AbstractRule` and uses `tslint.RuleFailure` system
195
196
## Usage Examples
197
198
**Enforce consistent formatting**:
199
```bash
200
# Run TSLint with prettier rule
201
npx tslint --project tsconfig.json
202
203
# Auto-fix formatting issues
204
npx tslint --project tsconfig.json --fix
205
```
206
207
**Typical TSLint configuration with prettier**:
208
```json
209
{
210
"extends": ["tslint-plugin-prettier", "tslint-config-prettier"],
211
"rules": {
212
"prettier": [true, {
213
"singleQuote": true,
214
"trailingComma": "es5",
215
"printWidth": 100
216
}]
217
}
218
}
219
```
220
221
**Custom ignore configuration**:
222
```json
223
{
224
"rules": {
225
"prettier": [true, null, {
226
"ignorePath": "build/.prettierignore",
227
"editorconfig": false
228
}]
229
}
230
}
231
```
232
233
## Types
234
235
```typescript { .api }
236
// TypeScript integration types
237
import * as ts from 'typescript';
238
import * as tslint from 'tslint';
239
import * as prettier from 'prettier';
240
241
// Rule implementation extends TSLint's AbstractRule
242
class Rule extends tslint.Rules.AbstractRule {
243
apply(sourceFile: ts.SourceFile): tslint.RuleFailure[];
244
}
245
246
// Configuration types for rule arguments
247
type RuleArguments = [
248
PrettierConfig | string | null,
249
{ editorconfig?: boolean; ignorePath?: string }?
250
];
251
252
type PrettierConfig = prettier.Options;
253
```