no-magic-numbers
Disallow magic numbers (numeric literals without a named constant)
Next step
no-magic-numbers ships in eslint-plugin-conventions, with 6 of its 15 rules in the recommended preset.
npm install -D eslint-plugin-conventionsimport { configs } from 'eslint-plugin-conventions';
export default [configs.recommended];
Disallow numeric literals whose meaning is not carried by a named constant
Rule Details
if (retries > 3) makes the reader reverse-engineer what 3 means;
if (retries > MAX_RETRIES) does not. The rule reports numeric literals used
directly in logic and offers a suggestion to extract a named constant.
Structural, allowlisted exceptions keep the rule quiet where a bare number IS
the clearest spelling: 0, 1, -1, 2 (indexing, off-by-one arithmetic,
parity), and any literal that initialises a named variable (const retries = 3, const WINDOW_MS = 60 * 1000) — the name carries the meaning. A numeric
object key ({ 404: 'Not found' }) is not reported either.
Each further exemption has an option:
| Option | Default | Exempts |
|---|---|---|
ignore | [] | These numbers; -42 is matched as written (ignore: [-42]) |
ignoreArrayIndexes | true | An integer index: items[42] |
detectObjects | false | When true, object values ({ timeout: 5000 }) are reported |
ignoreLoopBounds | true | A for loop's init, test and update: i < 42 |
ignoreLengthComparisons | true | An equality with a .length: xs.length === 42 |
ignoreDefaultValues | true | A default value: (x = 42) => x |
ignoreEnums | true | An enum member's value: enum E { A = 42 } |
ignoreBitwiseExpressions | false | When true, an operand of &, |, ^, <<, >>, >>> |
ignoreNumericArrays | true | A data array of two or more numbers: [42, 43] |
namedConstArithmetic | true | Arithmetic of literals that initialises a named variable |
Examples
❌ Incorrect
setTimeout(poll, 5000);
if (attempts > 3) giveUp();✅ Correct
const TIMEOUT_MS = 5000;
const MAX_RETRIES = 3;
setTimeout(poll, TIMEOUT_MS);
if (attempts > MAX_RETRIES) giveUp();
const first = items[0]; // structural allowlist: 0, 1, -1, 2Configuration Examples
Basic Usage
// eslint.config.js
{
rules: {
'conventions/no-magic-numbers': 'warn',
},
}With options
{
rules: {
'conventions/no-magic-numbers': [
'warn',
{ ignore: [100], detectObjects: true, ignoreBitwiseExpressions: true },
],
},
}When Not To Use It
Test files and fixtures, where literal values are the point. Scope the rule to production source in your config rather than disabling it globally.
Use this rule
npm install -D eslint-plugin-conventionsimport conventions from 'eslint-plugin-conventions';export default [ { plugins: { 'conventions': conventions }, rules: { 'conventions/no-magic-numbers': 'error' }, },];npm install -D oxlint-plugin-conventions{ "jsPlugins": ["oxlint-plugin-conventions"], "rules": { "conventions/no-magic-numbers": "error" }}import { defineConfig } from 'vite-plus';export default defineConfig({ lint: { jsPlugins: ['oxlint-plugin-conventions'], rules: { 'conventions/no-magic-numbers': 'error', }, },});oxlint-plugin-conventions re-exports eslint-plugin-conventions/oxlint: the same rules under the same IDs, and no ESLint install. Why oxlint.
Did this rule catch something? Star the repo to get new CWE coverage as we ship it — or follow the AI-code-security benchmarks behind these rules.