Kubit ESLint Plugin

A lightweight, composable ESLint plugin for TypeScript and React projects

Zero-config presets with all the rules from eslint-config-kubit, now as a proper ESLint plugin. Compatible with OxLint and ESLint flat config.

Installation | Quick Start | Configs | Rules | Migration | Contributing

---

Why this plugin?

@kubit-ui-web/eslint-plugin-kubit replaces eslint-config-kubit with a better architecture:

eslint-config-kubit (old)	@kubit-ui-web/eslint-plugin-kubit (new)
Opaque function that hides everything	Transparent, composable flat configs
~15 plugins bundled as dependencies	All plugins bundled — one install, zero setup
Incompatible with OxLint	Use only what OxLint doesn't cover
isReact flag controls rule loading	Pick recommended or recommended-react
Must override to disable rules	Cherry-pick configs: base, typescript, react

Requirements

• Node.js: >= 20.19.0
• ESLint: >= 9.0.0

Installation

All ESLint plugins come bundled — one install, zero extra setup:

# Using pnpm (recommended)
pnpm add -D eslint @kubit-ui-web/eslint-plugin-kubit

# Using npm
npm install --save-dev eslint @kubit-ui-web/eslint-plugin-kubit

That's it. All plugins (TypeScript, React, a11y, Prettier, Perfectionist, Jest, etc.) are included as direct dependencies and installed automatically.

Quick Start

TypeScript project (no React)

// eslint.config.js
const eslint = require("@eslint/js");
const tseslint = require("typescript-eslint");
const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  kubit.configs.recommended,
];

React + TypeScript project

// eslint.config.js
const eslint = require("@eslint/js");
const tseslint = require("typescript-eslint");
const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  kubit.configs["recommended-react"],
];

Minimal (only Kubit custom rules)

For projects using OxLint for standard rules:

// eslint.config.js
const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [kubit.configs["kubit-rules"]];

Available Configs

Config	Description	Use case
recommended	All rules without React	ESLint only
recommended-react	All rules with React + a11y	ESLint only
oxlint	Only rules OxLint doesn't cover	ESLint + OxLint
kubit-rules	Only 2 Kubit custom rules	OxLint with minimal ESLint
base	General JS/ES6 rules	Cherry-pick
typescript	TypeScript-specific rules	Cherry-pick
react	React + a11y rules	Cherry-pick
compat	Browser compatibility	Optional

Composing configs

You can mix and match individual configs:

const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [
  // Only TypeScript + kubit custom rules (no base JS rules)
  kubit.configs.typescript,
  kubit.configs["kubit-rules"],
];

Overriding rules

All rules are visible and overridable:

const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [
  kubit.configs.recommended,
  {
    rules: {
      // Override any rule from the preset
      complexity: ["warn", { max: 10 }],
      "@typescript-eslint/no-explicit-any": "off",
      "no-console": "off",

      // Configure kubit rules with your aliases
      "kubit/no-index-import": [
        "error",
        {
          aliases: {
            "@/components": "./src/components/*",
            "@/utils": "./src/utils/*",
          },
        },
      ],
    },
  },
];

Custom Rules

Import & Export Rules

Rule	Description	Auto-fix
kubit/no-index-import	Disallow imports from index/barrel files	✅
kubit/no-relative-import-paths	Enforce absolute import paths	✅
kubit/enforce-named-exports	Disallow default exports for better tree-shaking	-

React / JSX Rules

Rule	Description	Auto-fix
kubit/jsx-pascal-case	Enforce PascalCase for JSX components	-
kubit/no-multi-comp	One component per file	-
kubit/jsx-sort-props	Enforce sorted JSX props	✅
kubit/no-inline-styles	Disallow inline style={{}} in JSX	-

Architecture Rules

Rule	Description	Auto-fix
kubit/no-public-field-interface	Enforce behavior-only interfaces (methods, not fields)	-
kubit/no-framework-in-core	Prohibit framework imports inside /core/	-
kubit/no-cross-boundary-import	Enforce architectural layer boundaries	-

Using with OxLint

All 10 kubit rules work natively in OxLint via the jsPlugins feature.

Option A: ESLint config (only rules OxLint doesn't cover)

// eslint.config.js
const kubit = require("@kubit-ui-web/eslint-plugin-kubit");

module.exports = [kubit.configs.oxlint];

Option B: OxLint config (load kubit rules directly in OxLint)

Use the ready-made .oxlintrc.json presets from the oxlint/ directory. Each preset already includes jsPlugins with a relative path, so the kubit plugin loads automatically:

// .oxlintrc.json
{
  "extends": [
    "./node_modules/@kubit-ui-web/eslint-plugin-kubit/oxlint/recommended.json",
  ],
}

Or pick individual configs:

// .oxlintrc.json
{
  "extends": [
    "./node_modules/@kubit-ui-web/eslint-plugin-kubit/oxlint/base.json",
    "./node_modules/@kubit-ui-web/eslint-plugin-kubit/oxlint/typescript.json",
    "./node_modules/@kubit-ui-web/eslint-plugin-kubit/oxlint/architecture.json",
  ],
}

Option C: Manual jsPlugins setup

Add the plugin directly to your .oxlintrc.json:

// .oxlintrc.json
{
  "jsPlugins": [
    {
      "name": "kubit",
      "specifier": "./node_modules/@kubit-ui-web/eslint-plugin-kubit/lib/index.js",
    },
  ],
  "rules": {
    "kubit/no-index-import": "error",
    "kubit/enforce-named-exports": "error",
    "kubit/no-framework-in-core": "error",
    "kubit/no-cross-boundary-import": "error",
    "kubit/jsx-pascal-case": "error",
    "kubit/no-multi-comp": "error",
    "kubit/jsx-sort-props": [
      "error",
      { "callbacksLast": true, "shorthandFirst": true, "reservedFirst": true },
    ],
    "kubit/no-inline-styles": "error",
    "kubit/no-public-field-interface": "error",
  },
}

OxLint presets

Preset	Contents
oxlint/recommended.json	Everything below combined
oxlint/base.json	JS quality + import/jest + kubit import rules
oxlint/typescript.json	TS rules + no-public-field-interface
oxlint/react.json	React + a11y + JSX kubit rules
oxlint/architecture.json	Layer boundaries + framework isolation

Comparison: what each config includes

Rule category	recommended	oxlint	kubit-rules
Kubit custom rules	10	10	2
Prettier formatting	1	1	-
JS code quality	~25	-	-
Import rules	3	-	-
Perfectionist	3	3	-
Jest	2	-	-
TypeScript	11	3	-
React + a11y	~60	-	-
Total rules	~60+	~20	2

Migrating from eslint-config-kubit

See the full Migration Guide for step-by-step instructions.

TL;DR:

- const eslintFlatConfig = require("eslint-config-kubit");
- module.exports = eslintFlatConfig({ isReact: false, tsConfigPath: "..." });
+ const kubit = require("@kubit-ui-web/eslint-plugin-kubit");
+ module.exports = [kubit.configs.recommended];

Development

pnpm install
pnpm test
pnpm test:watch
pnpm test:coverage
pnpm lint

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

This project uses Changesets for automatic version management and publishing.

Documentation

• Migration Guide
• Contributing Guide
• Code of Conduct
• Security Policy
• Changelog

License

Apache License 2.0 - see LICENSE for details.

---

Made with care by the Kubit Team