repository·main·Indexed 25 days ago
https://github.com/azat-io/eslint-plugin-perfectionistAn ESLint plugin that enforces consistent code formatting by sorting data structures—including imports, objects, TypeScript types, enums, and JSX props—alphabetically, naturally, or by line length. All rules are automatically fixable. It provides pre-defined configurations such as recommended-alphabetical, recommended-natural, and recommended-line-length, as well as an Alphabet class for creating custom sorting orders.
ESLint Plugin Perfectionist is an ESLint plugin designed to enforce consistent code formatting by providing rules for sorting various data structures. It helps maintain code quality, readability, and uniformity across a project by automating the organization of elements like:
The perfectionist/sort-modules rule sorts module imports and exports. It was introduced in version v4.0.0. You can configure it using either ESLint Flat Config or Legacy Config formats.
// Flat Config (eslint.config.js)
import perfectionist from 'eslint-plugin-perfectionist'
export default [
{
plugins: {
perfectionist,
},
rules: {
'perfectionist/sort-modules': [
'error',
{
type: 'alphabetical',
order: 'asc',
fallbackSort: { type: 'unsorted' },
ignoreCase: true,
specialCharacters: 'keep',
partitionByComment: false,
partitionByNewLine: false,
newlinesBetween: 'ignore',
newlinesInside: 'ignore',
groups: [
'declare-enum',
'export-enum',
'enum',
['declare-interface', 'declare-type'],
['export-interface', 'export-type'],
['interface', 'type'],
'declare-class',
'class',
'export-class',
'declare-function',
'export-function',
'function'
],
customGroups: [],
useExperimentalDependencyDetection: true,
},
],
},
},
]For ESLint Flat Config (eslint.config.js), import the plugin and add it to the plugins object. You can then enable specific rules under the rules section.
// eslint.config.js
import perfectionist from 'eslint-plugin-perfectionist'
export default [
{
plugins: {
perfectionist,
},
rules: {
'perfectionist/sort-imports': 'error',
},
},
]The sort-variable-declarations rule enforces a consistent order of variable declarations within a scope. This helps improve code readability and maintainability by providing a predictable structure for variables in functions or modules.
Supported sorting strategies include:
// Example of alphabetical sorting
const API_KEY = 'e7c3b6d4-7b7d-4b3b-8b3b-7b3b7b3b7b3b',
apiUrl = 'https://api.perfectionist.dev',
data = fetchData(),
isAuthenticated = checkAuth(),
user = getCurrentUser()
const config = loadConfig(),
database = connectToDatabase(),
environment = process.env.NODE_ENV,
logger = createLogger(),
server = createServer()To use the recommended alphabetical configuration in a legacy ESLint setup (using .eslintrc.js), extend the plugin:perfectionist/recommended-alphabetical-legacy configuration.
// .eslintrc.js
module.exports = {
extends: [
'plugin:perfectionist/recommended-alphabetical-legacy',
],
}The recommended-natural configuration enables all eslint-plugin-perfectionist rules using natural sorting in ascending order. Unlike alphabetical sorting, natural sorting handles strings containing both letters and numbers intuitively (e.g., item-1, item-2, item-10). This is ideal for version files, task lists, or datasets where numerical values are present and human-readable order is preferred.
// Flat Config (eslint.config.js)
import perfectionist from 'eslint-plugin-perfectionist'
export default [
perfectionist.configs['recommended-natural'],
]To use this plugin, you must first install ESLint v8.45.0 or greater, followed by the perfectionist plugin.
npm install --save-dev eslint
npm install --save-dev eslint-plugin-perfectionistnpm install --save-dev eslint
npm install --save-dev eslint-plugin-perfectionistThe sort-enums rule enforces a consistent and predictable order for TypeScript enum members. This improves code readability and makes it easier to identify missing or duplicate entries. The rule can sort enums alphabetically or by line length.
enum Priority {
Critical = 'Critical',
High = 'High',
Low = 'Low',
Medium = 'Medium',
None = 'None',
}
enum Status {
Cancelled = 'Cancelled',
Completed = 'Completed',
InProgress = 'In Progress',
NotStarted = 'Not Started',
OnHold = 'On Hold',
}The sort-modules rule enforces a consistent order of module members to improve readability and maintainability. It helps developers quickly locate members and understand the file structure by systematically sorting them.
This rule supports different sorting strategies, such as alphabetical or lineLength (sorting by the length of the line).
The perfectionist/sort-exports rule enforces a consistent order for exported members. You can configure it using either ESLint Flat Config or Legacy Config.
Common configuration options include:
type: The sorting strategy (e.g., 'alphabetical').order: The direction of sorting ('asc' or 'desc').fallbackSort: Defines how to handle items that don't fit the primary sorting strategy.ignoreCase: Boolean to determine if case should be ignored during sorting.specialCharacters: How to handle special characters (e.g., 'keep').partitionByComment: Whether to group exports by comments.partitionByNewLine: Whether to group exports by new lines.newlinesBetween: Controls newlines between sorted items.// Flat Config (eslint.config.js)
import perfectionist from 'eslint-plugin-perfectionist'
export default [
{
plugins: {
perfectionist,
},
rules: {
'perfectionist/sort-exports': [
'error',
{
type: 'alphabetical',
order: 'asc',
fallbackSort: { type: 'unsorted' },
ignoreCase: true,
specialCharacters: 'keep',
partitionByComment: false,
partitionByNewLine: false,
newlinesBetween: 'ignore',
newlinesInside: 'ignore',
groups: [],
customGroups: [],
},
],
},
},
]For projects using the legacy .eslintrc.js format, add perfectionist to the plugins array and configure the perfectionist/sort-modules rule in the rules object.
// .eslintrc.js
module.exports = {
plugins: [
'perfectionist',
],
rules: {
'perfectionist/sort-modules': [
'error',
{
type: 'alphabetical',
order: 'asc',
fallbackSort: { type: 'unsorted' },
ignoreCase: true,
specialCharacters: 'keep',
partitionByComment: false,
partitionByNewLine: false,
newlinesBetween: 'ignore',
newlinesInside: 'ignore',
groups: [
'declare-enum',
'export-enum',
'enum',
['declare-interface', 'declare-type'],
['export-interface', 'export-type'],
['interface', 'type'],
'declare-class',
'class',
'export-class',
'declare-function',
'export-function',
'function'
],
customGroups: [],
useExperimentalDependencyDetection: true,
},
],
},
}The sort-named-imports rule enforces a standardized ordering of named imports to improve code readability and navigation. It allows you to sort imports either alphabetically or by line length.
Important: If you are using the standard ESLint sort-imports rule, you should disable it to prevent conflicts with this rule.
// Example of sorted named imports (alphabetical)
import {
createContext,
useEffect,
useId,
useLayoutEffect,
useReducer,
useRef,
useState,
} from 'react'
import {
createBrowserRouter,
Link,
Route,
RouterProvider,
} from 'react-router-dom'
import { useDispatch, useStore } from 'react-redux'