@verkstedt/lint

Linting configuration for verkstedt projects

Links

• 🔍 Packages using this

verkstedt internal

• 🗪 Chat
• 🗒 Tasks

Technical design

See DESIGN.md.

Installation

Automatic

npx @verkstedt/lint@latest .

Manual

Details

1. Install:

   npm install --save-dev eslint prettier @verkstedt/lint

   If you are using TypeScript, also:

   npm install --save-dev jiti

2. Make your tsconfig.json extend ours:

   {
     "$schema": "https://json.schemastore.org/tsconfig",
     "extends": "@verkstedt/lint/tsconfig",

3. Create prettier.config.ts (or prettier.config.mjs)

   export { default as default } from '@verkstedt/lint/prettier';

   …and an empty .prettierignore:

   touch .prettierignore

   [!NOTE] EsLint is set up to also use Prettier, so you don’t have to run it separately, but you can, if you e.g. want to do just the formatting in your editor.

4. Create eslint.config.ts (or eslint.config.mjs)

   import { createVerkstedtConfig } from '@verkstedt/lint/eslint';
   import { defineConfig } from 'eslint/config';
   
   export default defineConfig([
     await createVerkstedtConfig({
       dir: import.meta.dirname,
       // If you have TypeScript files that are NOT included in your tsconfig (e.g.
       // config files or scripts), you specify them here.
       // https://typescript-eslint.io/packages/parser/#allowdefaultproject
       allowDefaultProject: ['*.config.*'],
       // Custom config for no-restricted-imports rule
       // https://eslint.org/docs/latest/rules/no-restricted-imports
       noRestrictedImportsConfig: {},
     }),
   ]);

Migration from @verkstedt/eslint-config-verkstedt

Details

1. Remove all *eslint*, *prettier* and *stylelint* packages you have installed and remove old Prettier and EsLint config files.

2. Commit as something like “chore: Remove old linting config”.

3. Run the script from Automatic installation above.

4. Commit.

5. Run eslint --fix

6. Commit.

7. Fix any remaining linting errors and commit.

8. Check if you need to restore any of customisation you had in your old config files (they may be included in new config files!). Consider not adding things back to keep config consistent across projects.

[!NOTE] In some codebases, you may get a lot of errors from @typescript-eslint/no-explicit-any and @typescript-eslint/no-unsafe-* rules. Best approach is to temporarily disable them and merge new config like that, but plan to refactor the codebase to enable them back.

TypeScript 7

This package does not use the TypeScript API itself and works with whichever typescript your project installs. typescript-eslint, however, still needs the TypeScript 6 API. To lint a TypeScript 7 project, install both, using the aliases recommended by the TypeScript team:

npm install --save-dev typescript@npm:@typescript/typescript6 @typescript/native@npm:typescript@7

This gives you:

• tsc from TypeScript 7 (via @typescript/native), used by your build and type checks
• typescript resolving to the TypeScript 6 API (via @typescript/typescript6), used by typescript-eslint and editors
• tsc6 if you ever need the TypeScript 6 compiler explicitly

Both TypeScript versions declare a tsc binary and npm links whichever it installs last. If npx tsc --version reports TypeScript 6 after adding the aliases, run a clean install (npm ci) to get TypeScript 7.

Editors that load node_modules/typescript will find only the API re-export there, without the bundled lib.*.d.ts files. Point your editor’s TypeScript at node_modules/@typescript/old (TypeScript 6) or node_modules/@typescript/native (TypeScript 7) instead.

Note

TODO When typescript-eslint version with TypeScript 7 support ships, remove this section.

First run

npx eslint .

Running this for the first time might ask you to install some additional packages.

Tests

Tests are organised as separate packages. They are set up as npm workspaces. Running npm test will run eslint in all workspace test packages.

To check how the current config behaves in real projects, run npm run test-consumers. It clones every repository in the verkstedt GitHub organisation that depends on @verkstedt/lint, installs this working copy into each of them and runs eslint.

Debugging

Run with NODE_DEBUG=@verkstedt/lint to see some debug logs.

Known caveats

• No accessibility (jsx-a11y) rules for now. eslint-plugin-jsx-a11y has not yet shipped ESLint 10 support; the upstream PR is open at jsx-eslint/eslint-plugin-jsx-a11y#1081. Once that lands we will apply its recommended config whenever isFrontend is true. Also remove uninstalling the plugin in install.sh.

• Installation script overwrites extends in tsconfig.json. If your project already extends something you should copy options from ./typescript/tsconfig.base.json to your tsconfig and keep your extends as it is.

Security advisories

• GHSA-238p-pmpm-9mq7 katex
  • overridden in package.json to use ^0.19.0
  • pulled in by @eslint/markdown (tracked in #753) → micromark-extension-math (fix in #14), which requires katex@^0.16
• GHSA-vfj7-8cjw-p6xm braces
  • no update path exists, disputed by the library author
  • doesn’t affect us, as we only match patterns we write ourselves
  • npm audit fix --force downgrades eslint-plugin-lingui

License

ISC