Skip to content

Commit b5022d6

Browse files
kremakrema
committed
docs: update README to clarify builder functionality and version compatibility
1 parent 6c00203 commit b5022d6

File tree

1 file changed

+98
-218
lines changed

1 file changed

+98
-218
lines changed

‎README.md‎

Lines changed: 98 additions & 218 deletions
Original file line numberDiff line numberDiff line change
@@ -1,235 +1,115 @@
1-
# Angular ESLint + Stylelint Linter
1+
# Angular ESLint + Stylelint Builder
22

3-
[![npm version](https://badge.fury.io/js/@krema%2Fangular-eslint-stylelint-builder.svg)](https://badge.fury.io/js/@krema%2Fangular-eslint-stylelint-builder) ![node workflow](https://github.com/krema/angular-eslint-stylelint-builder/actions/workflows/integration-test.yml/badge.svg) ![node workflow](https://github.com/krema/angular-eslint-stylelint-builder/actions/workflows/unit-test.yml/badge.svg) ![angular versions](https://img.shields.io/badge/angular-v9--v15-%2523DD0031.svg?flat-square&logo=angular&labelColor=ff0000&color=grey)
3+
[![npm version](https://badge.fury.io/js/@krema%2Fangular-eslint-stylelint-builder.svg)](https://badge.fury.io/js/@krema/angular-eslint-stylelint-builder)
4+
![integration test](https://github.com/krema/angular-eslint-stylelint-builder/actions/workflows/integration-test.yml/badge.svg)
5+
![unit test](https://github.com/krema/angular-eslint-stylelint-builder/actions/workflows/unit-test.yml/badge.svg)
46

5-
An Angular CLI builder inspired by [@angular-eslint/builder](https://github.com/angular-eslint/angular-eslint/tree/master/packages/builder) for linting Angular applications using [ESLint](https://eslint.org/) and [stylelint](https://stylelint.io/) in one easy step.
7+
A unified Angular CLI builder for linting Angular projects with [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/) in a single step.
8+
9+
---
10+
11+
## Version Compatibility
12+
13+
- **< 2.0.0**: Supports Angular **v9 – v16** and **Stylelint ≤ 15**
14+
- **>= 2.0.0**: Supports Angular **v17 – v20** and **Stylelint 16+**
15+
16+
---
17+
18+
## Features
19+
20+
- Lint both TypeScript and stylesheets in one command
21+
- Supports ESLint and Stylelint configuration and ignore patterns
22+
- Output to file or console, with multiple formatter options
23+
- Caching for faster linting
24+
- Fine-grained control over warnings, errors, and exit codes
25+
26+
---
627

728
## Prerequisites
829

9-
Before using this linter, please ensure that you have already installed and configured **eslint** and **stylelint**, for example, by setting up `.eslintrc` and `.stylelintrc` files. For more information on converting TSLint to ESLint in Angular projects, please check out the [@angular-eslint](https://github.com/angular-eslint/angular-eslint) project.
30+
- Angular CLI project (v9+)
31+
- ESLint and Stylelint installed and configured (e.g., `eslint.config.js` for flat config, or `.eslintrc` for legacy config, and `stylelint.config.js` for Stylelint)
1032

11-
## Install
33+
---
1234

13-
`npm install --save-dev @krema/angular-eslint-stylelint-builder`
35+
## Installation
1436

15-
## Usage
37+
```bash
38+
npm install --save-dev @krema/angular-eslint-stylelint-builder
39+
```
1640

17-
Add the builder `@krema/angular-eslint-stylelint-builder:lint` to the lint task in your *angular.json*.
41+
---
1842

19-
**angular.json**
43+
## Usage
2044

21-
> projects &#8594; \<my-project> &#8594; architect &#8594; lint
45+
1. **Update your `angular.json`**
2246

23-
Replace the builder of `@angular-eslint` with `@krema/angular-eslint-stylelint-builder`:
47+
Replace the default lint builder with this one:
2448

25-
```diff
26-
"lint": {
27-
- "builder": "@angular-eslint/builder:lint",
28-
+ "builder": "@krema/angular-eslint-stylelint-builder:lint",
49+
```json
50+
"lint": {
51+
"builder": "@krema/angular-eslint-stylelint-builder:lint",
2952
"options": {
30-
- "lintFilePatterns": ["**/*.ts"]
31-
+ "eslintFilePatterns": ["**/*.ts"],
32-
+ "stylelintFilePatterns": ["**/*.scss"]
53+
"eslintFilePatterns": ["**/*.ts"],
54+
"stylelintFilePatterns": ["**/*.scss"]
3355
}
34-
}
56+
}
57+
```
58+
59+
2. **Run linting**
60+
61+
```bash
62+
ng lint
63+
```
64+
65+
---
66+
67+
## Configuration Options
68+
69+
| Name | Default | Description | Required | Linter |
70+
|--------------------------|-------------------|-----------------------------------------------------------------------------|----------|-----------|
71+
| **Basic configuration:** |
72+
| `eslintFilePatterns` | `[]` | Files/globs for ESLint | Yes | eslint |
73+
| `eslintConfig` | | Path to ESLint config (supports both flat config `eslint.config.js` and legacy `.eslintrc.*`) | No | eslint |
74+
| `stylelintFilePatterns` | `[]` | Files/globs for Stylelint | Yes | stylelint |
75+
| `stylelintConfig` | | Path to Stylelint config (`stylelint.config.js` or legacy `.stylelintrc.*`) | No | stylelint |
76+
| `noEslintrc` | `false` | Disable `.eslintrc.*` and `package.json` config | No | eslint |
77+
| `fix` | `false` | Auto-fix fixable issues | No | both |
78+
| **Cache-related:** |
79+
| `eslintCache` | `false` | Enable ESLint cache | No | eslint |
80+
| `stylelintCache` | `false` | Enable Stylelint cache | No | stylelint |
81+
| `eslintCacheLocation` | `.eslintcache` | ESLint cache file/directory | No | eslint |
82+
| `stylelintCacheLocation` | `.stylelintcache` | Stylelint cache file/directory | No | stylelint |
83+
| `eslintCacheStrategy` | `metadata` | ESLint cache strategy (`metadata` or `content`) | No | eslint |
84+
| **File Enumeration:** |
85+
| `eslintIgnorePatterns` | `[]` | Glob patterns to ignore (ESLint 9+) | No | eslint |
86+
| `stylelintIgnorePatterns`| `[]` | Glob patterns to ignore (Stylelint 16+) | No | stylelint |
87+
| **Output:** |
88+
| `outputFile` | | Write report to file instead of console | No | both |
89+
| `format` | `stylish` | Output formatter (see [ESLint formatters](https://eslint.org/docs/user-guide/formatters/)) | No | both |
90+
| `silent` | `false` | Hide output text | No | both |
91+
| **Handling warnings:** |
92+
| `quiet` | `false` | Only show errors (ignore warnings) | No | both |
93+
| `maxWarnings` | `-1` | Max warnings before nonzero exit code | No | both |
94+
| `force` | `false` | Succeed even if there are lint errors | No | both |
95+
96+
---
97+
98+
## Example
99+
100+
```json
101+
"lint": {
102+
"builder": "@krema/angular-eslint-stylelint-builder:lint",
103+
"options": {
104+
"eslintFilePatterns": ["src/**/*.ts"],
105+
"stylelintFilePatterns": ["src/**/*.scss"],
106+
"fix": true
107+
}
108+
}
35109
```
36110

37-
Run `ng lint`:
38-
39-
![](.github/assets/terminal.png)
40-
41-
## Configuration
42-
43-
You can configure the following options:
44-
45-
<table>
46-
<tr>
47-
<th>Name</th>
48-
<th>Default Value</th>
49-
<th>Description</th>
50-
<th>Required</th>
51-
<th>Linter</th>
52-
</tr>
53-
<tr>
54-
<td colspan="5"><b>Basic configuration:</b></td>
55-
</tr>
56-
<tr>
57-
<td>eslintFilePatterns</td>
58-
<td>[]</td>
59-
<td>
60-
One or more files/dirs/globs to pass directly to ESLint&#39;s lintFiles()
61-
method. i.e. [&quot;src/**/*.ts&quot;]
62-
</td>
63-
<td>true</td>
64-
<td>eslint</td>
65-
</tr>
66-
<tr>
67-
<td>eslintConfig</td>
68-
<td></td>
69-
<td>
70-
Use this configuration, overriding .eslintrc.*config options if present
71-
</td>
72-
<td></td>
73-
<td>eslint</td>
74-
</tr>
75-
<tr>
76-
<td>stylelintFilePatterns</td>
77-
<td>[]</td>
78-
<td>
79-
One or more files/dirs/globs to pass directly to stylelint&#39;s lint()
80-
method. [&quot;src/**/*.scss&quot;]
81-
</td>
82-
<td>true</td>
83-
<td>stylelint</td>
84-
</tr>
85-
<tr>
86-
<td>stylelintConfig</td>
87-
<td>&nbsp;</td>
88-
<td>Path to the stylelint configuration file</td>
89-
<td></td>
90-
<td>stylelint</td>
91-
</tr>
92-
<tr>
93-
<td>noEslintrc</td>
94-
<td>false</td>
95-
<td>
96-
Disables use of configuration from .eslintrc.* and package.json files.
97-
</td>
98-
<td></td>
99-
<td>eslint</td>
100-
</tr>
101-
<tr>
102-
<td>fix</td>
103-
<td>false</td>
104-
<td>
105-
Automatically fix, where possible, violations reported by rules (may
106-
overwrite linted files)
107-
</td>
108-
<td></td>
109-
<td>eslint, stylelint</td>
110-
</tr>
111-
<tr>
112-
<td colspan="5"><b>Cache-related:</b></td>
113-
</tr>
114-
<tr>
115-
<td>eslintCache</td>
116-
<td>false</td>
117-
<td>
118-
Store the results of processed files so that ESLint only operates on the
119-
changed ones
120-
</td>
121-
<td></td>
122-
<td>eslint</td>
123-
</tr>
124-
<tr>
125-
<td>stylelintCache</td>
126-
<td>false</td>
127-
<td>
128-
Store the results of processed files so that stylelint only operates on
129-
the changed ones
130-
</td>
131-
<td></td>
132-
<td>stylelint</td>
133-
</tr>
134-
<tr>
135-
<td>eslintCacheLocation</td>
136-
<td>.eslintcache</td>
137-
<td>Path to the cache file or directory</td>
138-
<td></td>
139-
<td>eslint</td>
140-
</tr>
141-
<tr>
142-
<td>stylelintCacheLocation</td>
143-
<td>.stylelintcache</td>
144-
<td>Path to the cache file or directory</td>
145-
<td></td>
146-
<td>stylelint</td>
147-
</tr>
148-
<tr>
149-
<td>eslintCacheStrategy</td>
150-
<td>metadata</td>
151-
<td>
152-
Strategy to use for detecting changed files in the cache. Can be either
153-
metadata or content
154-
</td>
155-
<td></td>
156-
<td>eslint</td>
157-
</tr>
158-
<tr>
159-
<td colspan="5"><b>File Enumeration:</b></td>
160-
</tr>
161-
<tr>
162-
<td>eslintIgnorePatterns</td>
163-
<td>[]</td>
164-
<td>
165-
Array of glob patterns describing files to ignore (replaces <code>eslintIgnorePath</code> and <code>.eslintignore</code> in ESLint 9+)
166-
</td>
167-
<td></td>
168-
<td>eslint</td>
169-
</tr>
170-
<tr>
171-
<td>stylelintIgnorePatterns</td>
172-
<td>[]</td>
173-
<td>
174-
Array of glob patterns describing files to ignore (replaces <code>stylelintIgnorePath</code> and <code>.stylelintignore</code> in Stylelint 16+)
175-
</td>
176-
<td></td>
177-
<td>stylelint</td>
178-
</tr>
179-
<tr>
180-
<td colspan="5"><b>Output:</b></td>
181-
</tr>
182-
<tr>
183-
<td>outputFile</td>
184-
<td></td>
185-
<td>File to write report to instead of the console</td>
186-
<td></td>
187-
<td>eslint, stylelint</td>
188-
</tr>
189-
<tr>
190-
<td>format</td>
191-
<td>stylish</td>
192-
<td>
193-
The output is formatted by using the
194-
<a href="https://eslint.org/docs/user-guide/formatters/">
195-
ESLint Output formatter</a
196-
>
197-
</td>
198-
<td></td>
199-
<td>eslint, stylelint</td>
200-
</tr>
201-
<tr>
202-
<td>silent</td>
203-
<td>false</td>
204-
<td>Hide output text</td>
205-
<td></td>
206-
<td>eslint, stylelint</td>
207-
</tr>
208-
<tr>
209-
<td colspan="5"><b>Handling warnings:</b></td>
210-
</tr>
211-
<tr>
212-
<td>quiet</td>
213-
<td>false</td>
214-
<td>
215-
Only register violations for rules with an "error"-level severity (ignore
216-
"warning"-level)
217-
</td>
218-
<td></td>
219-
<td>eslint, stylelint</td>
220-
</tr>
221-
<tr>
222-
<td>maxWarnings</td>
223-
<td>-1</td>
224-
<td>Number of warnings to trigger nonzero exit code</td>
225-
<td></td>
226-
<td>eslint, stylelint</td>
227-
</tr>
228-
<tr>
229-
<td>force</td>
230-
<td>false</td>
231-
<td>Succeeds even if there was linting errors</td>
232-
<td></td>
233-
<td>eslint, stylelint</td>
234-
</tr>
235-
</table>
111+
---
112+
113+
## License
114+
115+
MIT

0 commit comments

Comments
 (0)