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
```