run oxlint and lint your code.
be in a nodejs project.
npm i --save-dev --save-exact @magic/lint"scripts": {
"lint": "lint"
}Then run:
npm run lint
# or
npm run lint src
npm run lint -flint [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.
oxlint only emits colors when its own stdout is a TTY, so piping its
output (which lint always does) would lose them. lint therefore
decides on color from its own stdout and passes the decision to
oxlint via its environment, so npm run lint in a terminal shows the
same colored output as running oxlint directly, while
lint | tee log.txt stays plain.
the decision respects the standard env vars, in this order of precedence:
NO_COLOR(set and non-empty) — no colors, even in a TTYFORCE_COLOR(set, not0) — colors, even when pipedlint's stdout is a TTY — colorsCI(set and non-empty) — colors, for CI logs- otherwise — no colors
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.
lint resolves the config in this order:
- explicit
--config/-cflag — passed through as-is (relative paths resolved againstcwd) - consumer config —
oxlint.config.tsin the current working directory (if it exists) - shared config — the built-in config from
@magic/lint(fallback)
this means you can:
- run
lintwith zero config in a new project (uses shared config) - add
oxlint.config.tsto your project to customize rules - run
lint -c my.config.tsfor one-off configs (e.g. CI, sub-projects)
| variable | purpose |
|---|---|
MAGIC_LINT_OXLINT_BIN |
override the oxlint binary path (for testing or custom builds) |
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 configWithout 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.
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.
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 - style / misc:
no-var,prefer-const,prefer-rest-params,prefer-spreadas errors - overrides for TS files: an (empty) override block for
*.ts,*.tsx,*.mts,*.ctsas a placeholder for per-file-type rules
See src/oxlint.config.js 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
colorEnv, // env for oxlint color output, see colors above
sharedConfigPath, // path to the shared config
consumerConfigName, // 'oxlint.config.ts'
config, // content of oxlint.config.ts
} from '@magic/lint'resolves the config file path per the resolution order above.
returns the path to the oxlint binary. respects MAGIC_LINT_OXLINT_BIN.
low-level: spawns oxlint with the given argv array. color is decided
via colorEnv() (see colors).
computes the env to pass to an oxlint child process for color output:
FORCE_COLOR=1 when color should be emitted, NO_COLOR=1 otherwise
(see colors). defaults to the current process's env
and stdout.
absolute path to this package's src/oxlint.config.js.
string 'oxlint.config.ts' — the filename checked in the consumer project.
reexport of oxlint.config.js
0- no issues found1- lint issues found, or an oxlint error (e.g. no files matched)
| specifier | provides |
|---|---|
@magic/lint |
named: resolveConfig, getOxlintBin, runOxlint, colorEnv, 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 |
AGPL-3.0 — see LICENSE for details.