@antelopejs/tooling-configs

@antelopejs/tooling-configs

Shared lint, format and dead-code presets for AntelopeJS repositories, plus a check for the version ranges of interface dependencies.

• oxlint and oxfmt replace Biome: lint, format and Tailwind class sorting, .vue included.
• ESLint stays for the Nuxt front ends, from a shared config, until oxlint lints .vue files.
• Knip learns the entry points of an AntelopeJS module.
• Every preset is a function: options adjust it without copying it.

What's in the box

Install

Node.js 24, or at least 22.18: oxlint reads oxlint.config.ts and loads JS plugins by executing TypeScript.

pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxfmt

The tools are optional peer dependencies, so add only the ones a repository uses:

Pin oxlint to the exact version this package uses for @oxlint/plugins (currently 1.81.0): the JS plugin API is still alpha and the two must move together.

oxlint

// oxlint.config.ts
import { defineConfig } from "oxlint";
import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint";

export default defineConfig({
  extends: [antelopePreset()],
  // oxlint reads this field only from the root config, never from a preset.
  options: { typeAware: true },
});

// package.json
{
  "scripts": {
    "lint": "oxlint",
    "lint:fix": "oxlint --fix",
  },
}

What the preset turns on

correctness is raised to error on purpose: oxlint reports it as warnings, and warnings never fail the command. Complexity and anti-slop start as warnings so a repository can work through its backlog before raising them to "error".

Import sorting is off because it moves value imports across side-effect imports, and in an AntelopeJS module import "./components" is what registers the decorated classes. Turn it on only where import order does not matter.

Options

antelopePreset({
  antiSlop: "error", // "warn" (default) | "error" | false
  importCycles: "warn", // "error" (default) | "warn" | false
  complexity: { maxParams: 8 }, // override thresholds or severity, or false
  importSorting: true, // false (default); needs eslint-plugin-perfectionist
  typeAware: false, // true (default); false when the repository has no oxlint-tsgolint
});

Add ignore patterns

oxlint does not merge ignorePatterns across extends: a root config that declares its own replaces the preset's. Spread the shared ones:

// oxlint.config.ts
import { defineConfig } from "oxlint";
import {
  ANTELOPE_IGNORE_PATTERNS,
  antelopePreset,
} from "@antelopejs/tooling-configs/oxc/lint";

export default defineConfig({
  extends: [antelopePreset()],
  ignorePatterns: [...ANTELOPE_IGNORE_PATTERNS, "playground/**"],
});

oxfmt

// oxfmt.config.ts
import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt";

export default antelopeFmtPreset();

// package.json
{
  "scripts": {
    "format": "oxfmt .",
    "format:check": "oxfmt --check .",
  },
}

The house style sets every field, so .editorconfig files cannot override it: printWidth 80, 2 spaces, semicolons, double quotes, trailingComma: "all". Fix the repository's .editorconfig to match anyway, so editors agree with the formatter.

The preset leaves import order to the linter and ignores CHANGELOG.md, which changelogen writes unformatted on every release. Other options of oxfmt pass through. Two are specific:

// oxfmt.config.ts
export default antelopeFmtPreset({
  ignorePatterns: ["frontend-vue/**"], // added to the shared ignores, not replacing them
  tailwindStylesheet: "./assets/css/main.css", // sorts Tailwind classes, replacing prettier-plugin-tailwindcss
});

Replace Biome

Delete biome.json and the @biomejs/biome dependency, point lint, lint:fix and format at oxlint and oxfmt, and port what the Biome config carried that the preset does not. Reformat in its own commit and list it in .git-blame-ignore-revs, which GitHub honours.

ESLint (Nuxt front ends)

oxlint does not lint .vue files yet, so the front end stays on ESLint:

// frontend-vue/eslint.config.mjs
import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";

export default antelopeNuxtConfig({ dirs: ["./playground"] });

@nuxt/eslint-config supplies the Vue and TypeScript rules. The preset only records where AntelopeJS layers differ: single-word page components, any and {} allowed, _-prefixed unused bindings, and import order left alone. It sets no formatting rule, since oxfmt formats .vue. Pass rules to layer your own on top, and declare @nuxt/eslint-config in the front end's package.json.

Knip

// knip.config.ts
import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip";

export default antelopeKnipConfig();

The defaults declare what Knip cannot infer for an AntelopeJS module:

• entry points: src/interfaces/**/*.ts (public API), src/test/** and antelope.test.ts (run by ajs module test), and scripts/**;
• ignored: dist/**, playground/**, .antelope/**, and the @antelopejs/* dependencies, which the runtime loads by name.

entry, project, ignore, ignoreDependencies and ignoreBinaries options are appended to the defaults. frontend-vue/ stays out of project, so a repository can opt it in through Knip's workspaces.

Interface ranges

@antelopejs/core keeps one copy of each @antelopejs/interface-* package, the one its implementing module installed, and refuses to start when a module declares a range that copy falls outside. An exact pin (0.1.7) or a 0.x caret (^0.1.2 stops at 0.2.0) therefore breaks startup at the next interface release.

antelopejs-check-interface-ranges fails on such a range in dependencies or optionalDependencies, in every package.json git tracks in the repository, from any directory:

An implementer must never be handed a breaking minor it does not implement. workspace:, file: and link: specs are skipped. Pass paths to check only those manifests.

// package.json
{
  "scripts": {
    "lint": "oxlint && antelopejs-check-interface-ranges",
  },
}

Vendored anti-slop

src/oxc/anti-slop/ is a byte-identical copy of upstream, so it can be diffed against new releases; src/oxc/anti-slop/VENDORED.md records the commit and any local edit. This repository does not format or lint it. Upstream is MIT (src/oxc/anti-slop/LICENSE).

Documentation guardrail

The documentation action checks local Markdown links and explicitly labeled compatibility tables. Consumers can also opt in complete TypeScript examples and reference-page export coverage. Pin AntelopeJS/tooling-configs/actions/docs to a full commit SHA; no npm release is required. The guide includes CI and local commands, annotation syntax, and the checks that remain the author's responsibility.

Contributing

See CONTRIBUTING.md. pnpm install, then pnpm checks runs the typecheck, lint, format check and tests.

License

Apache-2.0, except the vendored anti-slop rules (MIT).