@voxpelli/eslint-config

April 21, 2026 · View on GitHub

npm version npm downloads neostandard javascript style Follow @voxpelli@mastodon.social

My personal ESLint config – a superset of the neostandard base config that I co-created and co-maintain.

This config contains a couple of more opinionated checks that I find helpful in my projects.

This is also the reference ESLint config for the types-in-JS workflow — JavaScript with JSDoc type annotations validated by tsc. The JSDoc rules are specifically tuned for this approach: type-checking rules are deactivated (handled by tsc), while documentation-oriented JSDoc rules remain active.

Install

To easily install correct peer dependencies, you can use install-peerdeps:

install-peerdeps --dev @voxpelli/eslint-config

Usage

Add an eslint.config.js (or eslint.config.mjs if your project is CJS) that exports this config:

export { default } from '@voxpelli/eslint-config';

If you need to configure something, instead do:

import { voxpelli } from '@voxpelli/eslint-config';

export default voxpelli({
  cjs: true,            // Ensures the config has rules fit for a CJS context rather than an ESM context
  noMocha: true,        // By standard this config expects tests to be of the Mocha kind, but one can opt out
  noStyle: true,        // Disables all stylistic rules (@stylistic + perfectionist sorting) — also passed to neostandard
  browserFiles: ['client/**/*.js'], // Scopes browser globals and disables Node rules for matched files
  cliFiles: ['bin/**/*.js', 'scripts/**/*.js'], // Relaxes rules for CLI scripts (process.exit, console, sync I/O, etc.)
});

Passing an unknown option key throws a TypeError with a message pointing to the composable pattern — this catches common mistakes like placing custom rules inside the options object.

Custom rules, plugins, and other ESLint config go in separate objects after the spread — not inside the voxpelli() options (which only accepts the keys shown above plus neostandard options):

import { voxpelli } from '@voxpelli/eslint-config';

export default [
  ...voxpelli({ /* config options */ }),
  {
    rules: {
      'no-console': 'off',
      'func-style': ['warn', 'declaration'],
    },
  },
];

Re-exported utilities

Bundled plugins and parsers are re-exported so consumers can reference them in custom overrides without installing them as separate dependencies:

import { voxpelli, plugins, globals } from '@voxpelli/eslint-config';

export default [
  ...voxpelli({ ts: true }),
  {
    files: ['**/*.vue'],
    languageOptions: {
      parser: plugins['typescript-eslint'].parser,
    },
  },
];

Note: voxpelli() returns a flat config array. With ESLint 9.37+ you can also use defineConfig() from eslint/config which auto-flattens arrays — no spread needed:

import { defineConfig } from 'eslint/config';
import { voxpelli } from '@voxpelli/eslint-config';

export default defineConfig([
  voxpelli({ /* options */ }),
  { /* custom rules */ },
]);

defineConfig() also supports an extends key inside config objects, which is useful when you need to scope the inherited config to specific files:

import { defineConfig } from 'eslint/config';
import { voxpelli } from '@voxpelli/eslint-config';

export default defineConfig([
  {
    files: ['src/**/*.js'],
    extends: [voxpelli()],
  },
]);

Composable sub-configs

browserFiles and cliFiles are also exported as standalone config factories for cases where you want to apply their rule sets without using voxpelli() as the base:

import { browserFiles, cliFiles } from '@voxpelli/eslint-config';

export default [
  // your own base config …
  ...browserFiles(['client/**/*.js']),
  ...cliFiles(['bin/**/*.js']),
];

browserFiles(globs) — scopes browser globals and disables Node.js rules for matched files.

cliFiles(globs) — relaxes rules appropriate for CLI scripts: allows process.exit(), console, sync I/O, and top-level non-await patterns.

How does this differ from pure neostandard?

  • :stop_sign: = changed to error level
  • :warning: = changed to warn level
  • :mute: = deactivated
  • :wrench: = changed config

Markers can combine when a rule has both a severity change and a separate config change — e.g. a bullet may lead with :warning: (severity) and carry an inline :wrench: (other config tweak).

:wrench: Changed neostandard rules

  • :wrench: @stylistic/comma-dangle – changed – set to enforce dangling commas in arrays, objects, imports and exports (disabled by noStyle)
  • :warning: @stylistic/object-curly-newline – :wrench: changed – softened to warn; enforces multiline imports and exports when 4+ specifiers are present (disabled by noStyle)
  • :wrench: no-unused-vars – changed – sets "args": "all", "argsIgnorePattern": "^_", because I personally don't feel limited by Express error handlers + wants to stay in sync with TypeScript noUnusedParameters

:heavy_plus_sign: Added ESLint core rules

  • :warning: func-style – disallows function declarations, good to be consistent with how functions are declared
  • :warning: no-console – warns on existence of console.log and similar, as they are mostly used for debugging and should not be committed
  • :stop_sign: no-constant-binary-expression – errors when binary expressions are detected to constantly evaluate a specific way
  • :stop_sign: no-nonoctal-decimal-escape – there's no reason not to ban it
  • :stop_sign: no-unsafe-optional-chaining – enforces one to be careful with .? and not use it in ways that can inadvertently cause errors or NaN results
  • :warning: no-warning-comments – warns of the existence of FIXME comments, as they should always be fixed before pushing
  • :stop_sign: object-shorthand – requires the use of object shorthands for properties, more tidy

:package: Added ESLint rule packages

:wrench: Overrides of added ESLint rule packages

:heavy_plus_sign: Additional standalone ESLint rules

ESM specific rules

Unless one configures cjs: true these additional rules will be applied:

:wrench: Overrides of rules

  • :warning: func-style – enforces function declarations whenever an arrow function isn't used. Better to do export function foo () { than export const foo = function () {
  • :stop_sign: unicorn/prefer-module – changed – restored to its plugin:unicorn/recommended value of error

Can I use this in my own project?

You may want to use neostandard instead, it's the general base config that I help maintain for the community. If you follow the types-in-JS approach, this config provides battle-tested JSDoc rule tuning validated against 50+ downstream repositories.

I do maintain this project though as if multiple people are using it, so sure, you can use it, but its ultimate purpose is to support my projects.

I do follow semantic versioning, so the addition or tightening of any checks will trigger major releases whereas minor and patch releases should only ever have relaxation of rules and bug fixes.

Alternatives

See also