or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alphabet-utility.mdclass-module-rules.mdcollection-rules.mdimport-export-rules.mdindex.mdjsx-variable-rules.mdobject-rules.mdplugin-configuration.mdtypescript-rules.md
tile.json

tessl/npm-eslint-plugin-perfectionist

ESLint plugin for sorting various data such as objects, imports, types, enums, JSX props, etc.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/eslint-plugin-perfectionist@4.15.x

To install, run

npx @tessl/cli install tessl/npm-eslint-plugin-perfectionist@4.15.0

index.mddocs/

ESLint Plugin Perfectionist

ESLint Plugin Perfectionist is a comprehensive ESLint plugin that provides sorting rules for various JavaScript and TypeScript code structures. It offers 22 different rules to sort imports, exports, objects, arrays, types, enums, JSX props, and many other code elements. The plugin supports multiple sorting strategies (alphabetical, natural, line-length, custom) and includes auto-fix capabilities to automatically format code according to specified sorting preferences.

Package Information

  • Package Name: eslint-plugin-perfectionist
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install eslint-plugin-perfectionist
  • Peer Dependencies: ESLint >=8.45.0
  • Node Support: ^18.0.0 || >=20.0.0

Core Imports

ESM:

import perfectionistPlugin from "eslint-plugin-perfectionist";

CommonJS:

const perfectionistPlugin = require("eslint-plugin-perfectionist");

Alphabet utility (separate export):

import { Alphabet } from "eslint-plugin-perfectionist/alphabet";

Basic Usage

ESLint Configuration (ESLint 9+ Flat Config)

import perfectionistPlugin from "eslint-plugin-perfectionist";

export default [
  {
    plugins: {
      perfectionist: perfectionistPlugin,
    },
    rules: {
      "perfectionist/sort-objects": "error",
      "perfectionist/sort-imports": "error",
      "perfectionist/sort-named-imports": "error",
    },
  },
];

Using Predefined Configurations

import perfectionistPlugin from "eslint-plugin-perfectionist";

export default [
  perfectionistPlugin.configs["recommended-alphabetical"],
];

Legacy ESLint Configuration

module.exports = {
  plugins: ["perfectionist"],
  extends: ["plugin:perfectionist/recommended-natural-legacy"],
  rules: {
    "perfectionist/sort-objects": ["error", { type: "alphabetical" }],
  },
};

Architecture

ESLint Plugin Perfectionist is built around several key components:

  • Rules Engine: 22 individual ESLint rules for different code structures
  • Sorting Strategies: Multiple sorting algorithms (alphabetical, natural, line-length, custom)
  • Configuration System: Predefined configs and custom grouping options
  • Alphabet Utility: Advanced Unicode alphabet manipulation for custom sorting
  • Auto-fix System: Automatic code transformation with safety features

Capabilities

Plugin Configuration

Core plugin object with rules, predefined configurations, and metadata for ESLint integration.

interface ESLintPlugin {
  rules: {
    [ruleName: string]: Rule.RuleModule;
  };
  configs: {
    "recommended-alphabetical-legacy": Linter.LegacyConfig;
    "recommended-line-length-legacy": Linter.LegacyConfig;
    "recommended-natural-legacy": Linter.LegacyConfig;
    "recommended-custom-legacy": Linter.LegacyConfig;
    "recommended-alphabetical": Linter.Config;
    "recommended-line-length": Linter.Config;
    "recommended-natural": Linter.Config;
    "recommended-custom": Linter.Config;
  };
  meta: {
    version: string;
    name: string;
  };
}

Plugin Configuration

Import and Export Sorting Rules

Rules for organizing import and export statements, including support for TypeScript, side effects, and custom grouping.

// Main import sorting rule
const sortImports: Rule.RuleModule;

// Export sorting rules
const sortExports: Rule.RuleModule;
const sortNamedImports: Rule.RuleModule;
const sortNamedExports: Rule.RuleModule;

Import Export Rules

Object and Property Sorting Rules

Rules for sorting object properties, TypeScript object types, and destructured objects.

// Object property sorting
const sortObjects: Rule.RuleModule;
const sortObjectTypes: Rule.RuleModule;

Object Rules

TypeScript Type Sorting Rules

Specialized rules for TypeScript constructs including union types, intersection types, interfaces, and enums.

// TypeScript-specific sorting rules  
const sortUnionTypes: Rule.RuleModule;
const sortIntersectionTypes: Rule.RuleModule;
const sortInterfaces: Rule.RuleModule;
const sortEnums: Rule.RuleModule;
const sortHeritageClauses: Rule.RuleModule;

TypeScript Rules

Class and Module Sorting Rules

Rules for organizing class members, module exports, and decorators.

// Class and module organization
const sortClasses: Rule.RuleModule;
const sortModules: Rule.RuleModule;
const sortDecorators: Rule.RuleModule;

Class Module Rules

Array and Collection Sorting Rules

Rules for sorting arrays, Sets, Maps, and switch cases.

// Collection sorting rules
const sortArrayIncludes: Rule.RuleModule;
const sortSets: Rule.RuleModule;
const sortMaps: Rule.RuleModule;
const sortSwitchCase: Rule.RuleModule;

Collection Rules

JSX and Variable Sorting Rules

Rules for JSX props and variable declarations.

// JSX and variable rules
const sortJsxProps: Rule.RuleModule;
const sortVariableDeclarations: Rule.RuleModule;

JSX Variable Rules

Alphabet Utility

Advanced Unicode alphabet manipulation utility for creating custom sorting orders.

class Alphabet {
  static generateFrom(values: string[] | string): Alphabet;
  static generateRecommendedAlphabet(): Alphabet;
  static generateCompleteAlphabet(): Alphabet;
  
  prioritizeCase(casePriority: "lowercase" | "uppercase"): this;
  pushCharacters(values: string[] | string): this;
  removeCharacters(values: string[] | string): this;
  sortBy(sortingFunction: (a: string, b: string) => number): this;
  getCharacters(): string;
}

Alphabet Utility

Common Options

All rules support these base configuration options:

interface CommonOptions {
  /** Sorting strategy to use */
  type: "alphabetical" | "line-length" | "natural" | "custom";
  /** Sort direction */
  order: "asc" | "desc";
  /** Whether to ignore case when sorting */
  ignoreCase?: boolean;
  /** Locales for locale-aware sorting */
  locales?: NonNullable<Intl.LocalesArgument>;
  /** Custom alphabet string for custom sorting */
  alphabet?: string;
  /** How to handle special characters */
  specialCharacters?: "remove" | "trim" | "keep";
  /** Fallback sorting configuration */
  fallbackSort?: {
    type: "alphabetical" | "line-length" | "natural" | "custom" | "unsorted";
    order?: "asc" | "desc";
  };
}

interface AdvancedOptions {
  /** Partition elements by comment blocks */
  partitionByComment?: boolean | string | {
    block?: boolean | string;
    line?: boolean | string;
  };
  /** Partition elements by newlines */
  partitionByNewLine?: boolean;
  /** Control newlines between sorted groups */
  newlinesBetween?: "ignore" | "always" | "never" | number;
  /** Custom groups for advanced sorting */
  customGroups?: Record<string, string | string[]>;
  /** Groups configuration for organizing elements */
  groups?: (string | {
    newlinesBetween?: "ignore" | "always" | "never" | number;
    commentAbove?: string;
  })[];
  /** Patterns to ignore when sorting */
  ignorePattern?: string | string[] | {
    pattern: string;
    flags?: string;
  };
}