Magic Lint

2.6.1 verified Fri May 01 auth: no javascript

Magic Lint is an all-in-one configless lint tool that integrates ESLint, Stylelint, Prettier, lint-staged, and commitlint to streamline project initialization and code quality enforcement. Current stable version is 2.6.1, released with weekly or monthly cadence. It supports JavaScript, TypeScript, Vue, and React out of the box with zero configuration for linting and formatting, but requires users to provide their own config files (.eslintrc, .stylelintrc, .prettierrc, commitlint.config.js). Its key differentiator is the 'harmony' mode that resolves Prettier/ESLint conflicts by running Prettier first then ESLint. The package also provides CLI commands for staged files, commit message checking, and full directory linting. Unlike alternatives like eslint-config-prettier or prettier-eslint, magic-lint bundles everything together with a single CLI and supports commit hooks via Husky.

Common errors

error Error: Failed to load config "magic-lint" to extend from. ↓

cause Missing required configuration files (.eslintrc etc.) or incorrect extend name.

fix

Create .eslintrc file with proper content or use --eslint flag without extend.

error npx: command not found: magic-lint ↓

cause magic-lint is not installed or npx can't find it.

fix

Run 'npm install magic-lint --save-dev' first, or use 'npx --package magic-lint' to force install.

error Warning: Unknown option: --harmony. Use --help for available options. ↓

cause Using deprecated --harmony flag.

fix

Remove --harmony; harmony mode is now default.

error TypeError: Cannot read properties of undefined (reading 'config') ↓

cause Missing or malformed commitlint.config.js when using --commit flag.

fix

Create commitlint.config.js in the project root or specify correct path with --commit.config.

Warnings

breaking Husky v4 hooks configuration in package.json is not supported in v2 of magic-lint. Must use shell scripts in .husky directory. ↓

fix Migrate to Husky v7+ and use .husky/pre-commit and .husky/commit-msg shell scripts as shown in the documentation.

gotcha magic-lint requires configuration files (.eslintrc, .stylelintrc, .prettierrc, commitlint.config.js). It does not provide sensible defaults. ↓

fix Create the required configuration files in your project root. For example, .eslintrc with extends: ['eslint:recommended'].

deprecated The --harmony flag is deprecated in v2.6.1. Harmony mode is enabled by default. ↓

fix Remove --harmony flag; it is automatically enabled.

gotcha "npx husky add" command may fail on Windows. Use "node node_modules/.bin/husky add" instead. ↓

fix Use the node command: node node_modules/.bin/husky add .husky/pre-commit '...'

breaking Peer dependency @typescript-eslint/eslint-plugin requires version >=5.55.0, causing version conflicts in older projects. ↓

fix Update @typescript-eslint/eslint-plugin to version 5.55.0 or higher.

Install

npm install magic-lint

yarn add magic-lint

pnpm add magic-lint

Imports

magic-lint CLI
```
npx magic-lint --staged --eslint --stylelint --prettier --fix
```
This package is a CLI tool and does not export any JavaScript API.

Husky hook integration

wrong

magic-lint --staged --eslint --stylelint --prettier --fix

correct

npx --no-install magic-lint --staged --eslint --stylelint --prettier --fix

When using Husky v7+, use npx --no-install to avoid installing locally with each commit.

Commit message linting

wrong

magic-lint --commit --commit.config ./commitlint.config.js --commit.edit $1

correct

npx --no-install magic-lint --commit --commit.config ./commitlint.config.js --commit.edit $1

The --commit.edit argument with $1 is required for commit message linting in Husky commit-msg hook.

Quickstart

Shows quick setup with Husky v7+ and CLI usage for linting staged files and commit messages.

# Install as dev dependency
npm install magic-lint --save-dev

# Set up Husky and add pre-commit hook for staged files
npx husky-init && npm install
npx husky add .husky/pre-commit 'npx --no-install magic-lint --staged --eslint --stylelint --prettier --fix'

# Add commit-msg hook for commit message linting
npx husky add .husky/commit-msg 'npx --no-install magic-lint --commit --commit.config "$(dirname "$0")/../commitlint.config.js" --commit.edit "$1"'

# Now lint all files in src directory
npx magic-lint --prettier --eslint --stylelint src/