# oxlint-config-awesomeness Opinionated Oxlint config for software houses that want all their apps to feel the same. **559 rules** across **16 plugins**. Built for full-stack TypeScript monorepos with React, Next.js, Hono, Prisma, and more. ## Installation ``` npm install -D oxlint-config-awesomeness eslint-plugin-no-only-tests eslint-plugin-perfectionist eslint-plugin-unused-imports oxlint-plugin-react-doctor oxlint-tsgolint ``` > [!NOTE] > Oxlint resolves JS plugin specifiers from your project root, not from this > package, so the plugins have to be installed alongside it. They are declared as > peer dependencies: npm and pnpm install them for you, and Yarn will warn if any > are missing. > [!TIP] > `eslint-plugin-perfectionist` pulls in `@typescript-eslint/utils`, which still > caps TypeScript at `<6.1.0` and has no release allowing 7 yet. Since this config > requires TypeScript 7, that range can never be satisfied and pnpm reports an > unmet peer. Installs still succeed; only `strict-peer-dependencies` repos fail. > To silence it, add to your `pnpm-workspace.yaml`: > > ```yaml > peerDependencyRules: > allowedVersions: > "@typescript-eslint/utils>typescript": "7" > "@typescript-eslint/typescript-estree>typescript": "7" > "@typescript-eslint/project-service>typescript": "7" > "@typescript-eslint/tsconfig-utils>typescript": "7" > ``` ### Type-aware linting This config sets `options.typeAware`, which turns on the 59 typescript-eslint rules that need a type checker (`no-floating-promises`, `no-misused-promises`, `no-unnecessary-condition`, and the rest). Those rules run through `oxlint-tsgolint`, which is why it is in the install line above. `oxlint-tsgolint` is only an _optional_ peer of oxlint itself, so if it is missing you do not get an error: type-aware rules are skipped silently and your lint still exits zero. If you want to confirm they are running, add a floating promise to a file and check that `typescript(no-floating-promises)` fires. tsgolint is pinned to a TypeScript release. The `7.x` line targets TypeScript 7, matching the `typescript` version this config is built against, and its version scheme encodes that: `7.0.2001` is patch 1 against TypeScript 7.0.2. TypeScript 7 is therefore a peer dependency: tsgolint carries its own TypeScript 7 checker, so a repo still on TypeScript 6 would be linted by a different compiler than the one that builds it. ### Replacing `tsc --noEmit` oxlint can report TypeScript compiler diagnostics directly via `options.typeCheck`, which raises the question of whether a separate `tsc --noEmit` step is still needed. On a whole-project run the two agree: the same errors, the same TypeScript error codes, at the same positions. Three things to know before dropping the `tsc` step: - oxlint calls `typeCheck` **experimental** in its own configuration schema. - Type diagnostics follow the files being linted. `oxlint .` covers the same ground as `tsc`, but a targeted run (lint-staged, or linting one package) only type-checks what it lints, whereas `tsc` always checks the whole program. - `tsc` is still required wherever it emits, such as building declaration files. Only the `--noEmit` check is a candidate for removal. `typeCheck` is on by default here. The reason is the single diagnostic stream: one oxlint run reports type errors and lint errors in one format, which is what automated fixers consume, and it reuses the program tsgolint already built instead of starting a second `tsc` process. tsgolint carries its own TypeScript 7 checker, which is why TypeScript 7 is a peer dependency. On a repo still on TypeScript 6 this surfaces the TypeScript 7 upgrade work early rather than reporting anything false: checked against a TypeScript 6 codebase whose own `tsc` exits clean, the diagnostics oxlint reported were reproduced exactly, same codes and same positions, by running real TypeScript 7 `tsc` over the same files. To opt out, set it back in your own `oxlint.config.ts`: ```ts export default defineConfig({ extends: [config], options: { typeCheck: false }, }); ``` Type-aware rules only see types for files inside your tsconfig program. Plain `.js`, `.jsx`, `.mjs`, and `.cjs` files are usually outside it, where every expression resolves to `any` and the `no-unsafe-*` family would fire on every line, so this config turns those rules off for JavaScript. `typeCheck` is left off as well, since it reports TypeScript compiler diagnostics through the linter and every repo here already runs `tsc` separately. ### Unused suppressions This config sets `options.reportUnusedDisableDirectives` to `warn`. An `oxlint-disable` or `eslint-disable` comment that no longer suppresses anything is reported, whether the rule was turned off, renamed, or the code it covered was fixed. That includes directives naming rules oxlint does not know, such as `react-hooks-js/*` or `@next/next/*` left over from an ESLint setup. Pass `--report-unused-disable-directives-severity` on the command line to override it for one run. ## Usage This package ships an oxlint config object — installing it does **not** generate a config file. You opt in by importing it from your own `oxlint.config.ts`. The fastest way is the included scaffolder: ``` npx oxlint-config-awesomeness init ``` This creates `oxlint.config.ts` in the current directory with the extends boilerplate already wired up. Pass `--force` to overwrite an existing config. If you'd rather write the file yourself, here's all it needs to be: ```ts import awesomeness from "oxlint-config-awesomeness"; import { defineConfig } from "oxlint"; export default defineConfig({ extends: [awesomeness], }); ``` Then run `pnpm oxlint` or `npx oxlint`. ### shadcn/ui projects Projects built on shadcn/ui can also extend the design-system preset, which registers [`@shadcn/lint`](https://github.com/shadcn-ui/lint) and enables its six rules as errors (known Tailwind classes, theme colors, scale values, no inline styles, static class names, and component restyling limited to layout): ``` npm install -D @shadcn/lint ``` ```ts import awesomeness from "oxlint-config-awesomeness"; import shadcn from "oxlint-config-awesomeness/shadcn"; import { defineConfig } from "oxlint"; export default defineConfig({ extends: [awesomeness, shadcn], settings: { // Only needed when the components are imported from a package. shadcn: { componentImports: ["^@acme/ui/components/"] }, }, }); ``` `@shadcn/lint` is an optional peer dependency, so projects that skip the preset never load it. To give specific components more room, redefine `shadcn/no-restyle` with `contracts`; your setting replaces the preset's. ## Upgrading from 2.x 3.0 adds **28 new restriction-level rules** that error on patterns AI-generated code routinely produces. Existing 2.x codebases may see new lint errors on upgrade — this is intentional; each rule catches a real failure mode. **What's newly enforced:** - **TypeScript escape hatches** — `no-explicit-any`, `no-non-null-assertion`, `no-non-null-asserted-nullish-coalescing`, `no-require-imports`, `no-var-requires`, `no-import-type-side-effects`, `use-unknown-in-catch-callback-variable`, `promise-function-async`, `no-dynamic-delete`, `no-invalid-void-type`, `no-empty-object-type` - **React correctness** — `button-has-type` (defaults silently submit forms), `no-danger` (XSS vector), `no-unknown-property`; `react/jsx-no-useless-fragment` re-enabled via `pedantic` - **Modern JS / Node hygiene** — `unicorn/prefer-node-protocol`, `unicorn/prefer-number-properties`, `unicorn/prefer-modern-math-apis`, `unicorn/no-document-cookie`, `unicorn/no-process-exit`, `unicorn/no-abusive-eslint-disable`, `node/handle-callback-err`, `node/no-new-require`, `node/no-path-concat`, `promise/catch-or-return` - **Core ESLint** — `no-var`, `no-use-before-define`, `no-empty` - **Import graph** — `import/no-cycle` - **Accessibility** — `jsx-a11y/anchor-ambiguous-text` **What changed in overrides:** - New `bin/**` and `scripts/**` override turns off `no-console` and `unicorn/no-process-exit` for CLI entry points. - Test override extended: the new strict rules that produce noise in tests (`no-require-imports`, `no-var-requires`, `promise-function-async`, `no-non-null-asserted-nullish-coalescing`, `import/no-cycle`, `no-empty`, `no-use-before-define`) are off inside tests. **Fixing common failures:** | Error | Fix | | ----------------------------- | -------------------------------------------------------- | | `: any` / `as any` | Use `unknown` + narrowing, or a real type. | | `value!` | Narrow with a type guard or throw explicitly. | | ` // good ``` ### react/checked-requires-onchange-or-readonly Require `onChange` or `readOnly` when `checked` is used. ```tsx // bad // good ``` ### react/default-props-match-prop-types Require all defaultProps to have a corresponding non-required prop type. ```tsx // bad type Props = { name: string }; const Comp = ({ name }: Props) =>
{name}
; Comp.defaultProps = { age: 25 }; // good type Props = { name: string; age?: number }; const Comp = ({ name, age }: Props) =>
{name}
; Comp.defaultProps = { age: 25 }; ``` ### react/exhaustive-deps Verify the list of dependencies for Hooks like `useEffect` and `useCallback`. ```tsx // bad useEffect(() => { fetchData(id); }, []); // good useEffect(() => { fetchData(id); }, [id]); ``` ### react/forward-ref-uses-ref Require `forwardRef` components to use the `ref` parameter. ```tsx // bad const Comp = forwardRef((props, ref) =>
); // good const Comp = forwardRef((props, ref) =>
); ``` ### react/function-component-definition Enforce arrow-function components for both named and unnamed components. ```tsx // bad function Card() { return
; } // good const Card = () =>
; ``` ### react/iframe-missing-sandbox Require `sandbox` attribute on `