@magic/lint

run oxlint and lint your code.

html docs

• install
• usage
  • npm scripts
  • cli
  • configuration
    • config resolution order
    • using the shared config
    • extending the shared config
    • environment variables
  • exit codes
• package exports
• license

getting started

be in a nodejs project.

npm i --save-dev --save-exact @magic/lint

usage

npm scripts

"scripts": {
  "lint": "lint"
}

Then run:

npm run lint
# or
npm run lint src
npm run lint -f

cli

lint [paths]     - lint the given paths, or the current directory
lint -c conf.ts  - lint with the given config
lint -f          - fix as many issues as possible
lint -v          - echo the oxlint command

lint is a thin wrapper around the oxlint cli. it spawns oxlint with the resolved config and forwards its output and exit code.

configuration

your project must have an oxlint.config.ts in its root (process.cwd()), allowing you to tailor the rules to your codebase.

a different config can be given explicitly with --config.

config resolution order

lint resolves the config in this order:

1. explicit --config / -c flag — passed through as-is (relative paths resolved against cwd)
2. consumer config — oxlint.config.ts in the current working directory (if it exists)
3. shared config — the built-in config from @magic/lint (fallback)

this means you can:

• run lint with zero config in a new project (uses shared config)
• add oxlint.config.ts to your project to customize rules
• run lint -c my.config.ts for one-off configs (e.g. CI, sub-projects)

environment variables

variable	purpose
MAGIC_LINT_OXLINT_BIN	override the oxlint binary path (for testing or custom builds)

shared config

To customize the shared config, you must import and re-export it from your own oxlint.config.ts. This is mandatory for oxlint to find and apply the correct rules to your files:

// oxlint.config.ts
import config from '@magic/lint/config'

export default config

Without this import/export, oxlint will not pick up your custom configuration and will not find the files correctly. Your project's oxlint.config.ts is picked up automatically by the shared config once you re-export it, so no extra wiring is needed.

shared config rules

The shared config enables correctness rules as errors:

⚠️ note on ignorePatterns

When using the shared config, local ignorePatterns in your project's oxlint.config.ts do not work as expected. This is a limitation of how oxlint merges extended configs — ignorePatterns from the base config take precedence, and local patterns are ignored.

Workaround: create an oxlint.config.ts in your project root that imports and re-exports the shared config directly (instead of using extends):

// oxlint.config.ts
import config from '@magic/lint/config'

export default {
  ...config,
  ignorePatterns: [...config.ignorePatterns, 'src/custom/ignore'],
}

Then add your ignorePatterns (and any rule overrides) to this file. Since it's a direct re-export, you have full control over the config object.

---

shared config rules

The shared config enables correctness rules as errors:

• core: no-unused-vars, no-debugger, no-cond-assign, no-constant-condition, no-empty, no-unreachable, no-unsafe-negation, no-unsafe-optional-chaining, constructor-super, getter-return, no-class-assign, no-const-assign, no-dupe-class-members, no-dupe-keys, no-func-assign, no-import-assign, no-new-native-nonconstructor, no-obj-calls, no-redeclare, no-setter-return, no-this-before-super, no-unsafe-finally, preserve-caught-error, require-yield, use-isnan, valid-typeof, no-array-constructor, no-unused-expressions, curly, and more
• typescript: ban-ts-comment, no-duplicate-enum-values, no-empty-object-type, no-explicit-any, no-extra-non-null-assertion, no-misused-new, no-namespace, no-non-null-asserted-optional-chain, no-require-imports, no-this-alias, no-unnecessary-type-constraint, no-unsafe-declaration-merging, no-unsafe-function-type, no-wrapper-object-types, prefer-as-const, prefer-namespace-keyword, triple-slash-reference
• overrides for TS files: disables rules that TS compiler already enforces, adds no-var, prefer-const, prefer-rest-params, prefer-spread as errors

See src/oxlint.config.ts for the full rule set.

named exports (for advanced use):

import {
  resolveConfig, // resolve config path given args + cwd
  getOxlintBin, // get the oxlint binary path
  runOxlint, // run oxlint with raw args
  sharedConfigPath, // path to the shared config
  consumerConfigName, // 'oxlint.config.ts'
  config, // content of oxlint.config.ts
} from '@magic/lint'

resolveConfig(args, cwd)

resolves the config file path per the resolution order above.

getOxlintBin()

returns the path to the oxlint binary. respects MAGIC_LINT_OXLINT_BIN.

runOxlint(oxlintArgs, cwd)

low-level: spawns oxlint with the given argv array.

sharedConfigPath

absolute path to this package's src/oxlint.config.ts.

consumerConfigName

string 'oxlint.config.ts' — the filename checked in the consumer project.

config

reexport of oxlint.config.js

exit codes

• 0 - no issues found
• 1 - lint issues found, or an oxlint error (e.g. no files matched)

package exports

specifier	provides
@magic/lint	named: resolveConfig, getOxlintBin, runOxlint, sharedConfigPath, consumerConfigName, config (shared config object)
@magic/lint/bin	CLI entry point (src/bin.js)
@magic/lint/config	the shared oxlint config (import and re-export it from your oxlint.config.ts) — mandatory for oxlint to find and apply rules to your files
@magic/lint/types	TypeScript declarations

license

AGPL-3.0 — see LICENSE for details.