|
1 | 1 | # eslint-config-sparkpost |
2 | | -ESLint configuration for Javascript based SparkPost projects |
3 | | - |
4 | | - |
5 | | - |
6 | | -## Notes for Docs in Libraries |
7 | | - |
8 | | -This config has extra rules specifically around JSDocs to help have better documentation in our libraries. |
9 | | -This can help in knowledge sharing and will hopefully promote better docs in our shared JS modules. |
10 | | - |
11 | | -To use, add the following to your `.eslintrc.json`: |
12 | | -```json |
13 | | -{ |
14 | | - "extends": "sparkpost/lib" |
15 | | -} |
| 2 | +ESLint configuration for Javascript and TypeScript based SparkPost projects |
| 3 | + |
| 4 | +## Upgrading from 2.x to 3.x |
| 5 | +There were several breaking changes including moving from ESLint 5.x to ESLint 8.x. This change alone caused some minimal breaking changes. Since |
| 6 | +we ultimately extend `eslint:recommended` in our base configuration, the upgrade from eslint 5.x to 8.x changed that 'recommended' config and the |
| 7 | +rules between versions have definitely changed. We compensated to match our existing config as best we could, but you may find other changes when |
| 8 | +running ESLint in your projects. |
| 9 | + |
| 10 | +We also moved several specific configs from overrides in the base config to their own specific configs. Mocha and TypeScript are used by some projects, |
| 11 | +however they are not used by every project so we have separated them to their own configs and moved their dependencies to optional peer dependencies |
| 12 | +so that we no longer need to install and maintain them in projects that don't use them. |
| 13 | + |
| 14 | +### Special Concerns for Mocha Based Projects |
| 15 | +Traditionally we've setup special rules for `mocha` based projects, however not all projects use `mocha`. This would lead to dependencies being |
| 16 | +installed that were unrelated to the project. For this reason, we have split `mocha` configuration into its own configuration. You can take |
| 17 | +advantage of it by extending `sparkpost/mocha` from this package. This will require you to install the plugin `eslint-plugin-mocha` in the project's |
| 18 | +dev dependencies. |
| 19 | + |
| 20 | +Example: |
| 21 | +```shell |
| 22 | +npm i -D eslint-plugin-mocha |
16 | 23 | ``` |
17 | | - |
18 | | - |
19 | | -The scripts below in this README are purely for reference and can make managing documentation in your shared lib much easier. |
20 | | - |
21 | | -### Useful NPM scripts |
| 24 | +In your `.eslintrc` file: |
22 | 25 | ```json |
23 | 26 | { |
24 | | - "scripts": { |
25 | | - "chk-changelog": "grep `node -e 'console.log(require(\"./package.json\").version);'` CHANGELOG.md || echo 'Please update CHANGELOG.md with your updates'; exit 255", |
26 | | - "docs": "doxdox index.js 'mocks/**/*.js' 'lib/**/*.js' --layout markdown --output DOCUMENTATION.md", |
27 | | - "lint": "eslint . --fix", |
28 | | - "nice-docs": "doxdox 'index.js' 'mocks/**/*.js' 'lib/**/*.js' --layout bootstrap --output docs/index.html && open docs/index.html", |
29 | | - "prepublishOnly": "npm run chk-changelog", |
30 | | - "prepush": "npm run docs -- && git add DOCUMENTATION.md && if git commit --no-verify -m \"`git rev-parse --abbrev-ref HEAD` Updated Documentation\"; then exit 0; else echo 'No documentation updates'; fi " |
31 | | - } |
| 27 | + "normal": "stuff <- comment", |
| 28 | + "overrides": [ |
| 29 | + { |
| 30 | + "files": ["test/**/*.spec.js"], |
| 31 | + "extends": ["sparkpost/mocha"] |
| 32 | + } |
| 33 | + ] |
32 | 34 | } |
33 | 35 | ``` |
34 | 36 |
|
35 | | -### Generating Docs |
36 | | -#### Install `doxdox` |
37 | | -```bash |
38 | | -npm i --save-dev doxdox |
39 | | -``` |
| 37 | +### Special Concerns for TypeScript Projects |
| 38 | +We have several `typescript` based projects, however not all projects use `typescript`. This would lead to dependencies being |
| 39 | +installed that were unrelated to the project. For this reason, we have split `typescript` configuration into its own configuration. You can take |
| 40 | +advantage of it by extending `sparkpost/typescript` from this package. This will require you to install several plugins and configs in the project's |
| 41 | +dev dependencies. |
40 | 42 |
|
41 | | -#### Add and modify the npm script. |
42 | | -The list below (`index.js 'mocks/**/*.js 'lib/**/*.js`) will probably need to be changed for your lib. |
43 | | -```json |
44 | | -{ |
45 | | - "docs": "doxdox index.js 'mocks/**/*.js' 'lib/**/*.js' --layout markdown --output DOCUMENTATION.md" |
46 | | -} |
| 43 | +Example: |
| 44 | +```shell |
| 45 | +npm i -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-prettier |
47 | 46 | ``` |
48 | | - |
49 | | -#### Run the script |
50 | | -```bash |
51 | | -npm run docs |
52 | | -``` |
53 | | -This will generate a ./DOCUMENTATION.md file that will include all JSDoc references in your module. |
54 | | - |
55 | | -#### Auto generating the docs |
56 | | -Given that you have husky installed, adding an npm script for `prepush` will automatically generate and commit docs anytime you push to git. |
| 47 | +In your `.eslintrc` file: |
57 | 48 | ```json |
58 | 49 | { |
59 | | - "prepush": "npm run docs -- && git add DOCUMENTATION.md && if git commit --no-verify -m \"`git rev-parse --abbrev-ref HEAD` Updated Documentation\"; then exit 0; else echo 'No documentation updates'; fi " |
| 50 | + "normal": "stuff <- comment", |
| 51 | + "extends": ["sparkpost/typescript"], |
| 52 | + "rules": { |
| 53 | + "other": "rules that override the base typescript config <- comment" |
| 54 | + } |
60 | 55 | } |
61 | 56 | ``` |
62 | 57 |
|
63 | | -#### Generating nicer docs |
64 | | -I recommend adding docs to your gitignore if its not already there. |
65 | | -```bash |
66 | | -echo docs >> .gitignore |
67 | | -``` |
| 58 | +## Docs in Libraries |
| 59 | +This config has extra rules specifically around JSDocs to help have better documentation in our libraries. |
| 60 | +This can help in knowledge sharing and will hopefully promote better docs in our shared JS modules. |
68 | 61 |
|
69 | | -Add the npm script: |
| 62 | +To use, add the following to your `.eslintrc` file: |
70 | 63 | ```json |
71 | 64 | { |
72 | | - "nice-docs": "doxdox 'index.js' 'mocks/**/*.js' 'lib/**/*.js' --layout bootstrap --output docs/index.html && open docs/index.html" |
| 65 | + "extends": "sparkpost/lib" |
73 | 66 | } |
74 | 67 | ``` |
75 | 68 |
|
76 | | -Run the npm script |
77 | | -```bash |
78 | | -npm run nice-docs |
79 | | -``` |
80 | | - |
81 | | -### Checking Changelogs |
| 69 | +### Automation for Checking Changelogs |
82 | 70 | #### Add the npm scripts |
83 | 71 | ```json |
84 | 72 | { |
85 | 73 | "chk-changelog": "grep `node -e 'console.log(require(\"./package.json\").version);'` CHANGELOG.md || echo 'Please update CHANGELOG.md with your updates'; exit 255", |
86 | 74 | "prepublishOnly": "npm run chk-changelog" |
87 | 75 | } |
88 | 76 | ``` |
89 | | -This will check your changelog for an entry for your current version when you publish. |
| 77 | +This will check your changelog for an entry for your current version when you publish. |
0 commit comments