@kitiumai/lint

Enterprise-ready, simple, and secure linting configuration package for Kitium AI projects.

API Reference (imports)

• ESLint configs: eslintBaseConfig, eslintReactConfig, eslintNodeConfig, eslintTypeScriptConfig, eslintJestConfig, eslintTestingLibraryConfig, eslintGraphQLConfig, eslintVueConfig, eslintNextjsConfig, eslintAngularConfig, eslintSvelteConfig, eslintSecurityConfig, eslintKitiumConfig
• Presets: configs (fullstack, fullstack_strict, react_spa, nextjs_app, node_api, graphql_api, vue_spa, library, monorepo, minimal, all)
• Utilities: createKitiumConfig, createKitiumPlugin
• Prettier: prettierConfig
• TypeScript: @kitiumai/lint/tsconfig/base, @kitiumai/lint/tsconfig/react, @kitiumai/lint/tsconfig/node
• Jest: @kitiumai/lint/jest (baseConfig, reactConfig, nextjsConfig, reactNativeConfig)
• Husky helpers: @kitiumai/lint/husky

Features

• ✅ Interactive Setup: Smart setup script to configure linting tools and project type
• ✅ Manual Control: Opt-in setup via npm run setup:lint for better monorepo support
• ✅ Project Type Support: React, Vue, Next.js, Angular, Svelte, Node.js, and more
• ✅ Modular Configurations: Separate configs for Base, React, Node.js, TypeScript, Jest, Testing Library, GraphQL, Vue, Next.js, Angular, Svelte
• ✅ TSLint Support: Optional TSLint configuration for additional TypeScript linting
• ✅ Auto-Detection: Automatically detects project type from package.json dependencies
• ✅ Migration Tool: Standalone migration script for converting existing ESLint v9 and TSLint configs
• ✅ Enterprise Security: Advanced security scanning with SonarJS and OWASP vulnerability detection
• ✅ ESLint 9 Compatible: Modern ESLint flat config format (FlatConfig)
• ✅ TypeScript First: Full TypeScript support with strict type checking
• ✅ React Ready: Complete React and React Hooks support with accessibility rules
• ✅ Testing Support: Jest configuration and Testing Library best practices
• ✅ Framework Support: Next.js, Vue.js, Angular, Svelte, and GraphQL configurations included
• ✅ Import & Module Discipline: Deterministic sorting, cycle detection, and guardrails against deep relative imports with module boundary hints
• ✅ Error Handling & Promise Safety: Enforces structured logging expectations and safer async flows using eslint-plugin-promise
• ✅ Performance & Correctness: Unicorn essentials to catch subtle perf regressions (prefer-query-selector, no-await-in-loop, etc.)
• ✅ Security Depth: SonarJS + Node hardening + enabled no-unsanitized/* XSS protection by default
• ✅ ESLint v9 Support: Full support for ESLint v9 flat config format
• ✅ Kitium UI Standards: Optional Kitium UI component naming & typing enforcement
• ✅ Git Hooks Integration: Pre-built Husky setup for automated code quality checks
• ✅ Accessibility First: Stricter React and Vue accessibility defaults; opt-in Vue a11y plugin support
• ✅ Code Formatting: Opinionated Prettier configuration included plus lint guardrails against stray local Prettier/EditorConfig files
• ✅ Shareable Presets: Pre-built configurations for common project patterns
• ✅ Easy to Use: Simple, composable configurations for any project type
• ✅ Zero Configuration: Works out of the box, no complex setup needed

Installation

npm install --save-dev @kitiumai/lint

# or
yarn add --dev @kitiumai/lint

# or
pnpm add --save-dev @kitiumai/lint

Quick Start

1. Run Setup (Recommended)

After installing @kitiumai/lint, run the setup script to configure your project:

npm run setup:lint

# or with yarn
yarn setup:lint

# or with pnpm
pnpm setup:lint

This will:

• Detect your project type
• Ask which tools you want (ESLint, TSLint, Prettier)
• Create configuration files (eslint.config.js, .prettierrc.js, etc.)
• Update your package.json with useful scripts

2. Manual Configuration (Alternative)

If you prefer to skip the interactive setup, manually create eslint.config.js:

For React + TypeScript Applications

Create eslint.config.js:

import { eslintReactConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [...eslintReactConfig, ...eslintTypeScriptConfig];

Create tsconfig.json:

{
  "extends": "@kitiumai/lint/tsconfig/react",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

For Node.js Backend

Create eslint.config.js:

import { eslintNodeConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [...eslintNodeConfig, ...eslintTypeScriptConfig];

Create tsconfig.json:

{
  "extends": "@kitiumai/lint/tsconfig/node"
}

For Vanilla JavaScript

Create eslint.config.js:

import { eslintBaseConfig } from "@kitiumai/lint";

export default [...eslintBaseConfig];

Usage & Tree-Shaking

• Prefer importing the specific subpath you need to keep consumer bundles small. Examples:

  • import base from "@kitiumai/lint/eslint/base"
  • import { prettierConfig } from "@kitiumai/lint/prettier"

• The package uses ESM and provides per-file subpath exports. Bundlers that support tree-shaking (Rollup, esbuild, webpack with Terser) will eliminate unused exports when consumers import only what they need.

• If you use the top-level barrel import { eslintBaseConfig } from "@kitiumai/lint", modern bundlers can still tree-shake unused exports, but importing subpaths is the most robust way to guarantee minimal bundle surface area across toolchains.

• TypeScript users: the package now ships index.d.ts with basic declarations for the common subpaths to improve IDE autocompletion and static imports.

If you want, create a minimal verification bundle with esbuild to validate that only the chosen config is included.

3. Run verify Before Committing

Use the consolidated quality gate to mirror CI locally:

pnpm verify
# Runs: pnpm lint && pnpm format && pnpm test

This ensures lint, formatting, and unit tests all pass before changes leave your machine.

4. Enable guardrails everywhere

• Husky hooks: The built-in husky/index.js runs pnpm lint:fix, pnpm format:fix, and lint-staged on pre-commit, then pnpm verify on pre-push so repos stay aligned with CI.
• CI template: Drop examples/ci-github-actions.yml into .github/workflows/quality.yml to run the same pnpm verify pipeline in GitHub Actions.
• Formatting guardrails: The base config errors on project-local Prettier or .editorconfig files so teams keep using the shared formatter defaults.

Strict presets

For teams that want every guardrail enabled by default, use the fullstack_strict preset which layers Kitium UI standards on top of the full-stack bundle:

import { configs } from "@kitiumai/lint";

export default configs.fullstack_strict;

Quick copy/paste examples

• React + TS: export default [...eslintReactConfig, ...eslintTypeScriptConfig];
• Node API + Security: export default [...eslintNodeConfig, ...eslintTypeScriptConfig, eslintSecurityConfig];
• Next.js app: export default [...configs.nextjs_app];
• Vue app: export default [...eslintVueConfig, ...eslintTypeScriptConfig];
• Library preset: export default [...configs.library];

Interactive Setup (Manual)

Run npm run setup:lint to interactively configure your linting setup.

The setup script will prompt you with questions to configure your project:

🎯 @kitiumai/lint Setup

Let's configure which tools you'd like to use for linting and formatting.

Use ESLint for JavaScript/TypeScript linting? [Y/n]:
📦 Detected ESLint v9
Keep using ESLint v9? [Y/n]:

Use TSLint for additional TypeScript linting? [y/N]:
Use Prettier for code formatting? [Y/n]:

Select your project type:
  > 1. Node.js
    2. React
    3. Next.js
    4. Vue
    5. Angular
    6. Svelte
    7. Vanilla JavaScript
    8. Vanilla TypeScript

Smart Migration Detection

If existing ESLint, TSLint, or Prettier configs are found, the setup will offer to migrate them:

📋 Found existing configurations:

  ✓ ESLint v9: eslint.config.js
  ✓ Prettier: .prettierrc.json

Would you like to migrate these configs to @kitiumai/lint? (y/n)

If you choose to migrate, the postinstall script will:

• Call the migrate script automatically
• Preserve all your custom rules
• Backup original configs
• Update to use @kitiumai/lint as the base

Based on your selections, the script automatically:

• Creates eslint.config.js (ESLint v9 flat config)
• Creates tslint.json (if selected)
• Creates .prettierrc.js (if selected)
• Creates .eslintignore and .prettierignore
• Adds npm scripts to package.json (only for selected tools)
• Saves your choices in .kitium-lint-setup.json for future runs

Automatic Project Detection

The setup automatically detects your project type based on dependencies:

• React if react is found
• Next.js if next is found (has priority over React)
• Vue if vue is found
• Angular if @angular/core is found
• Svelte if svelte is found
• Node.js (default for projects with server-side code)
• Vanilla JavaScript (for projects without frameworks)
• Vanilla TypeScript (for TypeScript-only projects)

Migration from Existing Configs

Have an existing ESLint or TSLint setup? Use the migration tool:

npm run migrate

The migration script:

• Detects existing configs (ESLint v9, TSLint, Prettier)
• Preserves custom rules while adopting @kitiumai/lint as base
• Backs up originals with timestamps (e.g., .eslintrc.backup.2025-11-19T15-33-27)
• Prompts for confirmation (opt-in, non-destructive)
• Supports non-interactive mode via environment variables:

  MIGRATE_AUTO_YES=true npm run migrate  # Auto-migrate all
  MIGRATE_AUTO_NO=true npm run migrate   # Skip all migrations

Migration Example

Before - ESLint v8 config:

{
  "extends": "airbnb",
  "rules": {
    "no-console": "warn",
    "react/prop-types": "off"
  }
}

After - Migrated to ESLint v9 flat config:

import { eslintReactConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [
  ...eslintReactConfig,
  ...eslintTypeScriptConfig,
  {
    name: "migrated-custom-rules",
    files: ["**/*.{js,jsx,ts,tsx}"],
    rules: {
      "no-console": "warn", // ✓ Preserved
      "react/prop-types": "off", // ✓ Preserved
    },
  },
];

Configuration Modules

ESLint Configurations

eslintBaseConfig

Core JavaScript/TypeScript linting rules applicable to all projects.

Includes:

• Code quality rules
• Best practices
• Variable management
• Formatting standards

eslintReactConfig

React-specific configuration with React hooks and accessibility rules.

Includes:

• React best practices
• React Hooks exhaustive deps checking
• JSX accessibility (a11y) rules
• Component pattern enforcement

Note: Extends baseConfig

eslintNodeConfig

Node.js backend configuration with security scanning.

Includes:

• Node.js-specific globals and rules
• Import sorting (simple-import-sort)
• Security vulnerability detection
• Best practices for server-side code

Note: Extends baseConfig

eslintTypeScriptConfig

Strict TypeScript configuration with comprehensive type checking.

Includes:

• Strict type checking rules
• TypeScript best practices
• Type safety enforcement
• Async/await validation

Note: Extends baseConfig

eslintJestConfig

Jest testing configuration for unit and integration tests.

Includes:

• Jest-specific globals and rules
• Test lifecycle best practices
• Snapshot testing guidelines
• Assertion validation

Files: **/*.test.{js,ts,jsx,tsx}, **/*.spec.{js,ts,jsx,tsx}

eslintTestingLibraryConfig

React Testing Library configuration for component testing best practices.

Includes:

• Accessibility-first query recommendations
• Implementation detail avoidance
• Async/await handling in tests
• User interaction patterns

Files: **/*.test.{jsx,tsx}, **/*.spec.{jsx,tsx}

eslintGraphQLConfig

GraphQL schema and query validation.

Includes:

• GraphQL query validation
• Schema compliance checking
• Field existence validation
• Deprecation warnings

Files: **/*.graphql, **/*.gql

eslintVueConfig

Vue.js 3 Single File Component (SFC) configuration.

Includes:

• Vue component best practices
• Script setup composition API support
• Template accessibility rules
• Vue lifecycle validation

Files: **/*.vue

eslintNextjsConfig

Next.js framework-specific configuration.

Includes:

• Image optimization rules
• Link component usage
• Performance best practices
• Font and script optimization

Extends: Base configuration

eslintKitiumConfig

Kitium component enforcement aimed at shared design-system packages.

Includes:

• Kt* component class naming requirements (KtButtonWeb, etc.)
• Props/Event interface naming conventions
• BaseProps/BaseComponent inheritance enforcement
• Required type exports for *.types.ts files

When to use: component libraries or apps that must follow Kitium UI patterns.

eslintAngularConfig

Angular framework-specific configuration with TypeScript support.

Includes:

• Directive selector conventions (attribute, camelCase prefix)
• Component selector conventions (element, kebab-case prefix)
• Lifecycle method validation
• TypeScript member ordering and accessibility rules
• Angular best practices and patterns

Files: **/*.ts (Angular components and services)

Example:

import { eslintAngularConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [...eslintAngularConfig, ...eslintTypeScriptConfig];

eslintSvelteConfig

Svelte framework-specific configuration with TypeScript support.

Includes:

• Svelte component best practices
• Block language configuration (TypeScript, SCSS)
• Template validation and linting
• Shorthand and directive usage rules
• Component structure enforcement

Files: **/*.svelte (Svelte components)

Example:

import { eslintSvelteConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [...eslintSvelteConfig, ...eslintTypeScriptConfig];

eslintSecurityConfig

Enhanced security scanning with advanced vulnerability detection.

Includes:

• OWASP Top 10 checks
• Code injection prevention
• SonarJS quality analysis
• Node.js security patterns
• XSS prevention (no-unsanitized)
• Cryptography best practices

Note: Recommended for all production applications

Prettier Configuration

import { prettierConfig } from "@kitiumai/lint";

export default prettierConfig;

Configuration:

• Print width: 100 characters
• Tab width: 2 spaces
• Single quotes for JavaScript/TypeScript
• Trailing commas for all multiline arrays/objects
• Automatic formatting for all supported file types

TypeScript Configurations

Available via extends in your tsconfig.json:

• @kitiumai/lint/tsconfig/base - Base TypeScript configuration
• @kitiumai/lint/tsconfig/react - React + TypeScript configuration
• @kitiumai/lint/tsconfig/node - Node.js + TypeScript configuration

Full Configuration Examples

Example 1: React + TypeScript + Tailwind

// eslint.config.js
import { eslintReactConfig, eslintTypeScriptConfig } from "@kitiumai/lint";
import tailwind from "eslint-plugin-tailwindcss";

export default [
  ...eslintReactConfig,
  ...eslintTypeScriptConfig,
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: { tailwindcss: tailwind },
    rules: {
      "tailwindcss/classnames-order": "warn",
      "tailwindcss/no-custom-classname": "warn",
    },
  },
];

Example 2: Node.js + Express

// eslint.config.js
import { eslintNodeConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [
  ...eslintNodeConfig,
  ...eslintTypeScriptConfig,
  {
    files: ["src/**/*.ts"],
    rules: {
      "no-console": ["warn", { allow: ["warn", "error", "info"] }],
    },
  },
];

Example 3: Monorepo Setup

// eslint.config.js
import {
  eslintBaseConfig,
  eslintReactConfig,
  eslintNodeConfig,
  eslintTypeScriptConfig,
} from "@kitiumai/lint";
import { prettierConfig } from "@kitiumai/lint";

export default [
  // Frontend apps
  {
    files: ["apps/web/**/*.{js,jsx,ts,tsx}"],
    extends: [...eslintReactConfig, ...eslintTypeScriptConfig],
  },
  // Backend services
  {
    files: ["apps/api/**/*.ts"],
    extends: [...eslintNodeConfig, ...eslintTypeScriptConfig],
  },
  // Shared utilities
  {
    files: ["packages/shared/**/*.ts"],
    extends: [...eslintBaseConfig, ...eslintTypeScriptConfig],
  },
];

Custom Rules Override

You can override any rules from the package configurations:

import { eslintReactConfig, eslintTypeScriptConfig } from "@kitiumai/lint";

export default [
  ...eslintReactConfig,
  ...eslintTypeScriptConfig,
  {
    name: "my-custom-rules",
    files: ["src/**/*.{ts,tsx}"],
    rules: {
      "@typescript-eslint/no-explicit-any": "warn", // Override to warning
      "react/prop-types": "off", // Disable rule
    },
  },
];

Extending Kitium Rules and Plugins

Need to enforce additional Kitium-specific conventions or register your own rules? Use the helper utilities exported by the package.

createKitiumConfig

Programmatically extend the Kitium ESLint config with additional rules, plugins, or overrides:

import { createKitiumConfig, eslintTypeScriptConfig } from "@kitiumai/lint";
import tailwindcss from "eslint-plugin-tailwindcss";

export default [
  ...createKitiumConfig({
    additionalRules: {
      "kitium/custom-rule": "warn",
    },
    additionalPlugins: {
      tailwindcss,
    },
    overrides: [
      {
        name: "kitium-tailwind",
        files: ["packages/ui/**/*.{ts,tsx}"],
        rules: {
          "tailwindcss/no-custom-classname": "warn",
        },
      },
    ],
  }),
  ...eslintTypeScriptConfig,
];

createKitiumPlugin

Merge your own custom rules into the Kitium ESLint plugin without rewriting it:

import { createKitiumPlugin } from "@kitiumai/lint";

const customRule = {
  meta: { type: "suggestion", docs: { description: "Require design tokens" } },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === "string" && node.value.includes("#")) {
          context.report({
            node,
            message: "Use design token variables instead of hex colors.",
          });
        }
      },
    };
  },
};

export default [
  {
    name: "kitium-with-custom",
    plugins: {
      kitium: createKitiumPlugin({
        additionalRules: {
          "design-tokens": customRule,
        },
        recommendedRules: {
          "kitium/design-tokens": "error",
        },
      }),
    },
    rules: {
      "kitium/design-tokens": "error",
    },
  },
];

These helpers keep the default Kitium behavior intact while giving you an ergonomic way to layer project-specific lints on top.

Shareable Configurations

Pre-built configuration presets for common project patterns. Use these to quickly set up linting for your project:

Quick Presets

// Use a preset
import {
  fullstack,
  react_spa,
  nextjs_app,
  node_api,
  graphql_api,
  vue_spa,
} from "@kitiumai/lint/configs";

export default [...fullstack]; // for full-stack apps

Available presets:

• fullstack - React + Node.js + TypeScript + Jest + Testing Library + Security
• react_spa - React Single Page Application with TypeScript
• nextjs_app - Next.js application with all features
• node_api - Node.js API server with security
• graphql_api - GraphQL server with Node.js and security
• vue_spa - Vue.js 3 application
• monorepo - Monorepo with multiple packages
• library - Library/package development
• minimal - Minimal JavaScript configuration
• all - All configurations enabled (for advanced users)

Example: Using Presets

// eslint.config.js
import { nextjs_app } from "@kitiumai/lint/configs";

export default [
  ...nextjs_app,
  {
    // Project-specific overrides
    files: ["src/**/*.ts"],
    rules: {
      "no-console": ["warn", { allow: ["error"] }],
    },
  },
];

Jest Configuration

Use the included Jest configurations:

// jest.config.js
import { reactConfig } from "@kitiumai/lint/jest";

export default {
  ...reactConfig,
  // Project-specific overrides
  collectCoverageFrom: ["src/**/*.{ts,tsx}", "!src/**/*.d.ts"],
};

Available Jest presets:

• baseConfig - Basic Node.js testing
• reactConfig - React component testing with jsdom
• reactNativeConfig - React Native testing
• nextjsConfig - Next.js application testing

Git Hooks with Husky

Set up automated code quality checks with Husky:

# Install dependencies
npm install --save-dev husky lint-staged

# Initialize husky
npx husky install

# Create pre-commit hook
npx husky add .husky/pre-commit 'npx lint-staged'

# Create pre-push hook
npx husky add .husky/pre-push 'npm run lint && npm test'

Add lint-staged configuration to package.json:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

For detailed setup, see the Husky documentation.

Security Features

The eslintSecurityConfig includes comprehensive security scanning:

OWASP Top 10 Protection

• Code Injection Prevention: Rules against eval, Function constructor, and dynamic code
• Cross-Site Scripting (XSS): Using eslint-plugin-no-unsanitized
• Insecure Deserialization: JSON parsing validation
• Broken Authentication: Type-safe credential handling with TypeScript

Advanced Scanning

• SonarJS Analysis: Code quality and security hotspots
• Node.js Specific: Buffer safety, child process warnings, path handling
• Static Analysis: Detects potential vulnerabilities at lint time
• Regex Security: Detection of unsafe regular expressions (ReDoS)
• Cryptography: Warnings for weak random number generation

Type Safety

• Strict TypeScript: Prevents many common security issues at compile time
• No Implicit Any: Enforces explicit type annotations
• Exhaustive Checks: Ensures all cases are handled

Use the security config on all production projects:

import { eslintSecurityConfig } from "@kitiumai/lint";

export default [
  // ... other configs
  eslintSecurityConfig,
];

Industry Standards Compliance

@kitiumai/lint is built on best practices from the industry's leading linting standards:

Standards Alignment

• Airbnb: 100% compliance with Airbnb JavaScript/TypeScript style guide
• Google: 100% compliance with Google JavaScript style guide
• Netflix: 100% compliance with Netflix JavaScript style guide
• Microsoft: 100% compliance with Microsoft TypeScript guidelines

Code Quality Standards

The following rules enforce production-grade code quality standards:

Complexity Management

• complexity: Limits cyclomatic complexity to 10 (industry standard)
• max-depth: Restricts nesting to 3 levels for readability
• max-lines-per-function: Functions kept under 50 lines (business logic level)
• max-statements: Max 20 statements per function to prevent god functions
• no-nested-ternary: Forces clarity over conciseness
• prefer-exponentiation-operator: Modern syntax for exponentiation

Code Safety

• no-bitwise: Warns on bitwise operations (rarely needed in modern JS)
• handle-callback-err: Ensures callback errors are handled
• no-buffer-constructor: Uses safe Buffer APIs
• no-path-concat: Prevents unsafe path concatenation

TypeScript Type Safety Standards

Naming Conventions

Enforces industry-standard naming:

// Variables: camelCase (or PascalCase for imports)
const userName = "John";
const isActive = true; // Boolean prefix: is/has/can/should/will/did

// Imports: camelCase or PascalCase allowed
import { DailyRotateFile } from "winston-daily-rotate-file";
import { createServer } from "http";

// Types/Interfaces: PascalCase
type UserProfile = { name: string };
interface IUser {
  id: string;
}

// Enums: UPPER_CASE
enum USERROLES {
  ADMIN,
  USER,
  GUEST,
}

// Object Literal Properties: flexible naming
const config = {
  DEBUG: true, // UPPER_CASE
  serverPort: 3000, // camelCase
  APIKey: "secret", // PascalCase
};

Async/Promise Safety (Microsoft Standards)

Prevents common async-related bugs:

• @typescript-eslint/await-thenable: Ensures promises are awaited
• @typescript-eslint/no-floating-promises: Catches unhandled promises
• @typescript-eslint/no-misused-promises: Validates promise usage in conditionals
• @typescript-eslint/only-throw-error: Only throw Error objects, not strings

Type Checking

• @typescript-eslint/no-explicit-any: Enforces explicit types (warn level)
• @typescript-eslint/no-unused-vars: Removes dead code
• @typescript-eslint/no-inferrable-types: Removes redundant type annotations
• @typescript-eslint/prefer-nullish-coalescing: Uses ?? for null checks
• @typescript-eslint/prefer-optional-chain: Uses optional chaining (.?)

Jest Testing Best Practices

Enforces quality testing patterns:

• jest/no-disabled-tests: Warns on .skip() tests (prevent forgotten tests)
• jest/no-focused-tests: Errors on .only() tests (prevents blocking CI)
• jest/no-identical-title: Prevents duplicate test names
• jest/valid-expect: Validates all assertions
• jest/no-conditional-expect: Ensures assertions always run
• jest/prefer-equality-matcher: Uses toBe over toEqual for primitives
• jest/prefer-each: Uses parametrized tests for clarity
• jest/no-large-snapshots: Warns on massive snapshot files (>50 lines)

Import Best Practices

Enforces clean module boundaries:

• import/no-cycle: Detects circular dependencies early
• import/no-self-import: Prevents importing from self
• import/consistent-type-specifier-style: Consistent type imports

Framework-Specific Standards

Each framework configuration follows its own best practices:

• React: ESLint React plugin + React Hooks rules from the official React team
• Next.js: Vercel's recommended Next.js optimizations
• Vue: Vue Community standards and Vue 3 Composition API best practices
• Angular: Google's Angular style guide and best practices
• Node.js: Node.js best practices for security and performance

npm Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --check .",
    "format:fix": "prettier --write .",
    "type-check": "tsc --noEmit",
    "verify": "pnpm lint && pnpm format && pnpm test"
  }
}

Optional Peer Dependencies

Install the relevant peers when you enable a preset:

| Feature / preset | Command | | -------------------- | ---------------------------------------------------------------------------------- | | React / Hooks / A11y | pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y | | Next.js | pnpm add -D @next/eslint-plugin-next | | Vue | pnpm add -D eslint-plugin-vue | | Testing Library | pnpm add -D eslint-plugin-testing-library | | Jest | pnpm add -D eslint-plugin-jest @types/jest | | GraphQL linting | pnpm add -D eslint-plugin-graphql graphql |

The interactive setup:lint wizard will prompt for these, but you can install them manually as shown above.

IDE Integration

VS Code

Install the following extensions:

• ESLint (dbaeumer.vscode-eslint)
• Prettier (esbenp.prettier-vscode)

Create .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": true
    }
  },
  "[typescript]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": true
    }
  },
  "[typescriptreact]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": true
    }
  }
}

Development and Testing

Run Tests

npm run test

Run Linting

npm run lint
npm run lint:fix

Format Code

npm run format
npm run format:check

Manual Setup and Re-running Setup

Running Setup Manually

If the postinstall script doesn't run during installation (e.g., due to npm script restrictions), you can manually trigger setup using the setup:lint script that was added to your package.json:

npm run setup:lint

This script is always added to your package.json by the postinstall process and can be used to:

• Manually run setup if installation was skipped
• Re-configure linting options
• Regenerate configuration files

Re-running Setup

To reconfigure your linting setup at any time:

npm run setup:lint

This will:

• Detect existing configurations (if any)
• Offer to migrate them
• Allow you to change your tool selections
• Update or regenerate configuration files
• Save your new preferences

Note: If the setup was already completed, you'll see your previous configuration and can choose to keep it or run the interactive setup again.

Troubleshooting

ESLint Configuration Not Created

If the configuration files aren't created, use the manual setup script:

1. Run Setup Script Manually

The setup:lint script is added to your package.json during installation. Run it anytime:

# npm
npm run setup:lint

# yarn
yarn setup:lint

# pnpm (recommended for monorepos)
pnpm setup:lint

This is required in monorepo environments to avoid blocking installs with interactive prompts.

2. Run Script Directly

Alternatively, run the setup script directly:

# npm
node node_modules/@kitiumai/lint/scripts/postinstall.js

# pnpm
pnpm exec node node_modules/@kitiumai/lint/scripts/postinstall.js

# yarn
yarn node node_modules/@kitiumai/lint/scripts/postinstall.js

3. Verify ESLint Installation

Ensure ESLint is properly installed:

npm list eslint

You should see ESLint v9 (9.0.0+) installed.

4. Check Node.js Version

@kitiumai/lint requires Node.js ≥18.0.0:

node --version

5. Check npm Scripts Config

Ensure npm scripts are not disabled:

npm config get ignore-scripts

If set to true, enable scripts:

npm config set ignore-scripts false

6. Clear npm Cache

Sometimes npm cache issues prevent script execution:

npm cache clean --force
npm install @kitiumai/lint

Verify Configuration Creation

After installation, check which configuration files were created:

# ESLint v9 flat config
ls -la eslint.config.js

# ESLint ignore file
ls -la .eslintignore

Still Having Issues?

If configuration files weren't created, check your setup configuration:

cat .kitium-lint-setup.json

To reset and re-run setup:

rm .kitium-lint-setup.json
node node_modules/@kitiumai/lint/scripts/postinstall.js

For additional help:

• GitHub Issues: https://github.com/kitium-ai/lint/issues
• GitHub Discussions: https://github.com/kitium-ai/lint/discussions

Compatibility

• Node.js: ≥ 18.0.0
• npm: ≥ 9.0.0
• ESLint: 8.50.0 or 9.0.0+ (automatic version detection)
• TypeScript: 4.8.0 or 5.0.0+ (optional, for TypeScript projects)

Contributing

Contributions are welcome! Please ensure all changes:

1. Follow the existing code style
2. Include appropriate tests
3. Update documentation
4. Pass linting checks

License

MIT

Support

For issues and questions:

• GitHub Issues: https://github.com/kitium-ai/lint/issues
• Discussions: https://github.com/kitium-ai/lint/discussions

Changelog

See CHANGELOG.md for version history and breaking changes.