@sripberger/eslint-config-ts v0.1.0
@sripberger/eslint-config-vurvey
Contains base ESLint configurations for TypeScript projects, forked from @batterii/eslint-config-vurvey.
Usage
To use ths configuration, first install this package and its peer dependencies as dev dependencies.
Then, create a file called .eslintrc.yaml
at the root of the
repository with the following contents:
extends: "@sripberger/eslint-config-ts"
Finally, create scripts in your package.json
for running the linter:
{
"scripts": {
"lint": "eslint . --ext .ts",
"lintfix": "eslint . --ext .ts"
}
}
Running these scripts will lint all files in the repo with a .ts
extension.
If needed on a per-project basis, you can make changes to the configuration within the project's
.eslintrc.yaml
file. As a general rule, however, shareable configuration should be preferred to
help ensure code style consistency between different repositories.
Creating New Environment-Specific Configs
In the event that we need to create additional environment-specific configurations, we can
extend this configuration to do so by creating a new repo for it and installing this
package as a dependency. Then, create a file called .eslintrc.yaml
with the following contents:
extends: "@batterii/eslint-config-vurvey/meta"
This establishes linter rules for linting the config files themselves. You'll want to create scripts
in your package.json
for running them:
{
"scripts": {
"lint": "eslint . --ext .ts",
"lintfix": "eslint . --ext .ts"
}
}
Running these scripts will lint all files in the new repo with a .js
extension, which should
include all the config files you create.
Next, create a file called test.js
with the following contents:
module.exports = {
extends: "@sripberger/eslint-config-ts/test",
};
Next, create a file called base.js
with the following contents:
module.exports = {
extends: "@sripberger/eslint-config-ts/base",
overrides: [{
extends: "./test.js",
files: ["*.test.ts"],
}],
};
Finally, create a file called index.js
with the following contents:
module.exports = {
extends: "./base.js",
overrides: [{
extends: "./test.js",
files: ["*.test.ts"],
}],
};
You can further edit these files to make environment-specific changes. main.js
should be used for
the main config, and test.js
should include overrides specific to test files. If your test files
may have different extensions than the ones listed in index.js
, you'll want to make sure to add
these to the files
array under overrides
.
index.js
should only be responsible for bringing together the main config and the test config. It
should not be edited to contain rule definitions of its own.
If you add any rules which rely on ESLint plugins, these plugins should be listed as peer dependencies instead of direct dpeendencies. See the Note on Peer Dependencies below for more information.
Once you're done setting up the configs yourself, you should add a README.md
file detailing the
purpose, usage, and organization of your config repo, similar to the ones that exist in our other
environment-specific config repos.
Modules
This package contains four modules, described below. For simplicity and for ESLint support, they are written as CommonJS modules in plain JavaScript.
base.js
This module contains the base configuration, containing rules which will be enforced in all TypeScript files in all Vurvey-related repositories, unless modified by a derviced config.
test.js
This module contains overrides which will be applied to the base config for linting automated test
files with the .test.ts
or spec.ts
extensions. This test
config mostly relaxes rules from the
base config instead of adding more restrictions. This is because such test code has a different
purpose than production-ready code, so we need not be as strict with it.
index.js
This module extends base.js
and adds the overrides from test.js
for files with the .test.ts
and .spec.ts
extensions. It is intended as a convenience to be used for environment-agnostic
projects and should not be changed to contain any rule definitions of its own. It should also not
be extended by other configs.
meta.js
This module contains configuration used for linting this project and other ESLint config projects. It does not extend the base configuration and instead is only concerned with rules for laying out and organizing our linter config files. It should not be extended by other configs.
Proposing Changes
Linter rules like these are a team effort-- especially ones that are re-used between many different teams working in many very different environments. All developers subject to these rules should feel free to propose changes so that we can arrive a set of common rules that work for everyone. To do this, simply open a pull request and give other affected devs the opportunity to discuss in comments.
For organization and tracking purposes, pull requests to this repo should focus on changing a small number of rules at a time. This will help keep discussion focused on individual conventions and concerns.
Publishing
npm version
and npm publish
can be used to publish this package as normal. These should be run
in the latest main
branch by someone with write access to the package on NPM. When doing so, a
preversion
script will lint the repo and a prepublishOnly
script will automatically push the
verison number commmit and tag to the GitHub repo.
Note that ESLint configuration changes can have massive effects on other developers and code bases.
When publishing a new version of this package, a breaking release should be made if one or
more rules changes has the potential to produce new linter errors (not warnings) which cannot be
auto-fixed by ESLint's --fix
flag.
If a breaking release of this package is made, breaking releases of all dependent environment-specific config packages should be made as well. Doing this will enable developers of affected repositories to upgrade to the breaking versions and address the new errors when they are able.
Note on Peer Dependencies
ESLint's developer guide for shareable configs recommends that such configs declare the ESLint version they need-- as well as versions for any plugins-- as peer dependencies rather than as direct dependencies. This expresses compatibility limitations while still ultimately leaving control over ESLint and its plugins to the repositories where ESlint will actually be run.
For more information about this approach, see this Node.js blog post on the subject.
1 year ago